

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>Ceph Dashboard Developer Documentation &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../../_static/css/custom.css" type="text/css" />

  
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
        <script src="../../../_static/jquery.js"></script>
        <script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
        <script src="../../../_static/doctools.js"></script>
        <script src="../../../_static/sphinx_highlight.js"></script>
    
    <script type="text/javascript" src="../../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../../genindex/" />
    <link rel="search" title="Search" href="../../../search/" />
    <link rel="next" title="Ceph Dashboard Design Goals" href="../../dashboard/ui_goals/" />
    <link rel="prev" title="Testing - Windows" href="../tests-windows/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../../../" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../">向 Ceph 贡献：开发者指南</a></li>
      <li class="breadcrumb-item active">Ceph Dashboard Developer Documentation</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../../../_sources/dev/developer_guide/dash-devel.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../../" class="icon icon-home"> Ceph
          

          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../start/">Ceph 简介</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../monitoring/">监控概览</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../architecture/">体系结构</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../">开发者指南</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../intro/">简介</a></li>
<li class="toctree-l2"><a class="reference internal" href="../essentials/">必备知识</a></li>
<li class="toctree-l2"><a class="reference internal" href="../merging/">何时、合并了什么</a></li>
<li class="toctree-l2"><a class="reference internal" href="../issue-tracker/">问题追踪器</a></li>
<li class="toctree-l2"><a class="reference internal" href="../basic-workflow/">基本工作流</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tests-unit-tests/">测试：单元测试</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testing_integration_tests/">测试：集成测试(Teuthology)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../running-tests-locally/">测试：在本地运行测试</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tests-windows/">测试: Windows</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Ceph Dashboard 开发者文档 (之前是 HACKING.rst)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#feature-design">Feature Design</a><ul>
<li class="toctree-l4"><a class="reference internal" href="../../dashboard/ui_goals/"> UI Design Goals</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#preliminary-steps">Preliminary Steps</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#vstart">vstart</a></li>
<li class="toctree-l4"><a class="reference internal" href="#host-based-vs-docker-based-development-environments">Host-based vs Docker-based Development Environments</a></li>
<li class="toctree-l4"><a class="reference internal" href="#vstart-on-your-host-system">vstart on your host system</a></li>
<li class="toctree-l4"><a class="reference internal" href="#docker">Docker</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#frontend-development">Frontend Development</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
<li class="toctree-l4"><a class="reference internal" href="#package-installation">Package installation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#adding-or-updating-packages">Adding or updating packages</a></li>
<li class="toctree-l4"><a class="reference internal" href="#setting-up-a-development-server">Setting up a Development Server</a></li>
<li class="toctree-l4"><a class="reference internal" href="#code-scaffolding">Code Scaffolding</a></li>
<li class="toctree-l4"><a class="reference internal" href="#build-the-project">Build the Project</a></li>
<li class="toctree-l4"><a class="reference internal" href="#build-the-code-documentation">Build the Code Documentation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#code-linting-and-formatting">Code linting and formatting</a></li>
<li class="toctree-l4"><a class="reference internal" href="#ceph-dashboard-and-bootstrap">Ceph Dashboard and Bootstrap</a></li>
<li class="toctree-l4"><a class="reference internal" href="#writing-unit-tests">Writing Unit Tests</a></li>
<li class="toctree-l4"><a class="reference internal" href="#running-unit-tests">Running Unit Tests</a></li>
<li class="toctree-l4"><a class="reference internal" href="#running-end-to-end-e2e-tests">Running End-to-End (E2E) Tests</a></li>
<li class="toctree-l4"><a class="reference internal" href="#writing-end-to-end-tests">Writing End-to-End Tests</a></li>
<li class="toctree-l4"><a class="reference internal" href="#visual-regression-testing">Visual Regression Testing</a></li>
<li class="toctree-l4"><a class="reference internal" href="#differences-between-frontend-unit-tests-and-end-to-end-e2e-tests-faq">Differences between Frontend Unit Tests and End-to-End (E2E) Tests / FAQ</a></li>
<li class="toctree-l4"><a class="reference internal" href="#further-help">Further Help</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-of-a-generator">Example of a Generator</a></li>
<li class="toctree-l4"><a class="reference internal" href="#frontend-typescript-code-style-guide-recommendations">Frontend Typescript Code Style Guide Recommendations</a></li>
<li class="toctree-l4"><a class="reference internal" href="#frontend-components">Frontend components</a></li>
<li class="toctree-l4"><a class="reference internal" href="#helper">Helper</a></li>
<li class="toctree-l4"><a class="reference internal" href="#terminology-and-wording">Terminology and wording</a></li>
<li class="toctree-l4"><a class="reference internal" href="#frontend-branding">Frontend branding</a></li>
<li class="toctree-l4"><a class="reference internal" href="#ui-style-guide">UI Style Guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="#error-handling">Error Handling</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#internationalization-i18n">Internationalization (i18n)</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#how-to-extract-messages-from-source-code">How to extract messages from source code?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#supported-languages">Supported languages</a></li>
<li class="toctree-l4"><a class="reference internal" href="#translating-process">Translating process</a></li>
<li class="toctree-l4"><a class="reference internal" href="#updating-translated-messages">Updating translated messages</a></li>
<li class="toctree-l4"><a class="reference internal" href="#add-a-new-release-resource-to-transifex">Add a new release resource to transifex</a></li>
<li class="toctree-l4"><a class="reference internal" href="#suggestions">Suggestions</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#accessibility">Accessibility</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li>
<li class="toctree-l4"><a class="reference internal" href="#accessibility-checkers">Accessibility checkers</a></li>
<li class="toctree-l4"><a class="reference internal" href="#color-contrast-checkers">Color contrast checkers</a></li>
<li class="toctree-l4"><a class="reference internal" href="#accessibility-linters">Accessibility linters</a></li>
<li class="toctree-l4"><a class="reference internal" href="#accessibility-testing">Accessibility testing</a></li>
<li class="toctree-l4"><a class="reference internal" href="#additional-guidelines">Additional guidelines</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#backend-development">Backend Development</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#unit-testing">Unit Testing</a></li>
<li class="toctree-l4"><a class="reference internal" href="#unit-tests-based-on-tox">Unit tests based on tox</a></li>
<li class="toctree-l4"><a class="reference internal" href="#api-tests-based-on-teuthology">API tests based on Teuthology</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-add-a-new-controller">How to add a new controller?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#implementing-proxy-controller">Implementing Proxy Controller</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-does-the-restcontroller-work">How does the RESTController work?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-use-a-custom-api-endpoint-in-a-restcontroller">How to use a custom API endpoint in a RESTController?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-restrict-access-to-a-controller">How to restrict access to a controller?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-create-a-dedicated-ui-endpoint-which-uses-the-public-api">How to create a dedicated UI endpoint which uses the ‘public’ API?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-access-the-manager-module-instance-from-a-controller">How to access the manager module instance from a controller?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-write-a-unit-test-for-a-controller">How to write a unit test for a controller?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-update-or-create-new-dashboards-in-grafana">How to update or create new dashboards in grafana?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-listen-for-manager-notifications-in-a-controller">How to listen for manager notifications in a controller?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-write-a-unit-test-when-a-controller-accesses-a-ceph-module">How to write a unit test when a controller accesses a Ceph module?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-add-a-new-configuration-setting">How to add a new configuration setting?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-run-a-controller-read-write-operation-asynchronously">How to run a controller read-write operation asynchronously?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-get-the-list-of-executing-and-finished-asynchronous-tasks">How to get the list of executing and finished asynchronous tasks?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-use-asynchronous-apis-with-asynchronous-tasks">How to use asynchronous APIs with asynchronous tasks?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-update-the-execution-progress-of-an-asynchronous-task">How to update the execution progress of an asynchronous task?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#how-to-deal-with-asynchronous-tasks-in-the-front-end">How to deal with asynchronous tasks in the front-end?</a></li>
<li class="toctree-l4"><a class="reference internal" href="#rest-api-documentation">REST API documentation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#error-handling-in-python">Error Handling in Python</a></li>
<li class="toctree-l4"><a class="reference internal" href="#plug-ins">Plug-ins</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../jaegertracing/">Tracing 开发者文档</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../cephadm/">Cephadm 开发者文档</a></li>
<li class="toctree-l2"><a class="reference internal" href="../debugging-gdb/">用 GDB 调试</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../hardware-monitoring/">硬件监控</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <section id="ceph-dashboard-developer-documentation">
<span id="dashdevel"></span><h1><a class="toc-backref" href="#id4" role="doc-backlink">Ceph Dashboard Developer Documentation</a><a class="headerlink" href="#ceph-dashboard-developer-documentation" title="Permalink to this heading"></a></h1>
<nav class="contents" id="table-of-contents">
<p class="topic-title">Table of Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#ceph-dashboard-developer-documentation" id="id4">Ceph Dashboard Developer Documentation</a></p>
<ul>
<li><p><a class="reference internal" href="#feature-design" id="id5">Feature Design</a></p></li>
<li><p><a class="reference internal" href="#preliminary-steps" id="id6">Preliminary Steps</a></p>
<ul>
<li><p><a class="reference internal" href="#vstart" id="id7">vstart</a></p></li>
<li><p><a class="reference internal" href="#host-based-vs-docker-based-development-environments" id="id8">Host-based vs Docker-based Development Environments</a></p>
<ul>
<li><p><a class="reference internal" href="#development-environment-on-your-host-system" id="id9">Development environment on your host system</a></p></li>
<li><p><a class="reference internal" href="#development-environments-based-on-docker" id="id10">Development environments based on Docker</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#vstart-on-your-host-system" id="id11">vstart on your host system</a></p></li>
<li><p><a class="reference internal" href="#docker" id="id12">Docker</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#frontend-development" id="id13">Frontend Development</a></p>
<ul>
<li><p><a class="reference internal" href="#prerequisites" id="id14">Prerequisites</a></p></li>
<li><p><a class="reference internal" href="#package-installation" id="id15">Package installation</a></p></li>
<li><p><a class="reference internal" href="#adding-or-updating-packages" id="id16">Adding or updating packages</a></p></li>
<li><p><a class="reference internal" href="#setting-up-a-development-server" id="id17">Setting up a Development Server</a></p></li>
<li><p><a class="reference internal" href="#code-scaffolding" id="id18">Code Scaffolding</a></p></li>
<li><p><a class="reference internal" href="#build-the-project" id="id19">Build the Project</a></p></li>
<li><p><a class="reference internal" href="#build-the-code-documentation" id="id20">Build the Code Documentation</a></p></li>
<li><p><a class="reference internal" href="#code-linting-and-formatting" id="id21">Code linting and formatting</a></p></li>
<li><p><a class="reference internal" href="#ceph-dashboard-and-bootstrap" id="id22">Ceph Dashboard and Bootstrap</a></p></li>
<li><p><a class="reference internal" href="#writing-unit-tests" id="id23">Writing Unit Tests</a></p></li>
<li><p><a class="reference internal" href="#running-unit-tests" id="id24">Running Unit Tests</a></p></li>
<li><p><a class="reference internal" href="#running-end-to-end-e2e-tests" id="id25">Running End-to-End (E2E) Tests</a></p>
<ul>
<li><p><a class="reference internal" href="#e2e-prerequisites" id="id26">E2E Prerequisites</a></p></li>
<li><p><a class="reference internal" href="#run-frontend-e2e-tests-sh" id="id27">run-frontend-e2e-tests.sh</a></p></li>
<li><p><a class="reference internal" href="#run-cephadm-e2e-tests-sh" id="id28">run-cephadm-e2e-tests.sh</a></p></li>
<li><p><a class="reference internal" href="#other-running-options" id="id29">Other running options</a></p></li>
<li><p><a class="reference internal" href="#cypress-cache-folder" id="id30">CYPRESS_CACHE_FOLDER</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#writing-end-to-end-tests" id="id31">Writing End-to-End Tests</a></p>
<ul>
<li><p><a class="reference internal" href="#the-pagerhelper-class" id="id32">The PagerHelper class</a></p></li>
<li><p><a class="reference internal" href="#subclasses-of-pagehelper" id="id33">Subclasses of PageHelper</a></p>
<ul>
<li><p><a class="reference internal" href="#helper-methods" id="id34">Helper Methods</a></p></li>
<li><p><a class="reference internal" href="#using-pagehelpers" id="id35">Using PageHelpers</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#code-style" id="id36">Code Style</a></p>
<ul>
<li><p><a class="reference internal" href="#describe-vs-it" id="id37"><code class="docutils literal notranslate"><span class="pre">describe()</span></code> vs <code class="docutils literal notranslate"><span class="pre">it()</span></code></a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#visual-regression-testing" id="id38">Visual Regression Testing</a></p>
<ul>
<li><p><a class="reference internal" href="#running-visual-regression-tests-locally" id="id39">Running Visual Regression Tests Locally</a></p></li>
<li><p><a class="reference internal" href="#capturing-screenshots" id="id40">Capturing Screenshots</a></p></li>
<li><p><a class="reference internal" href="#writing-more-visual-regression-tests" id="id41">Writing More Visual Regression Tests</a></p></li>
<li><p><a class="reference internal" href="#visual-regression-tests-in-jenkins" id="id42">Visual Regression Tests In Jenkins</a></p></li>
<li><p><a class="reference internal" href="#accepting-or-rejecting-differences" id="id43">Accepting or Rejecting Differences</a></p></li>
<li><p><a class="reference internal" href="#debugging-regressions" id="id44">Debugging Regressions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#differences-between-frontend-unit-tests-and-end-to-end-e2e-tests-faq" id="id45">Differences between Frontend Unit Tests and End-to-End (E2E) Tests / FAQ</a></p>
<ul>
<li><p><a class="reference internal" href="#what-are-e2e-unit-tests-designed-for" id="id46">What are E2E/unit tests designed for?</a></p></li>
<li><p><a class="reference internal" href="#which-e2e-unit-tests-are-considered-to-be-valid" id="id47">Which E2E/unit tests are considered to be valid?</a></p></li>
<li><p><a class="reference internal" href="#how-should-an-e2e-unit-test-look-like" id="id48">How should an E2E/unit test look like?</a></p></li>
<li><p><a class="reference internal" href="#what-should-an-e2e-unit-test-cover" id="id49">What should an E2E/unit test cover?</a></p></li>
<li><p><a class="reference internal" href="#what-should-an-e2e-unit-test-not-cover" id="id50">What should an E2E/unit test NOT cover?</a></p></li>
<li><p><a class="reference internal" href="#best-practices-guideline" id="id51">Best practices/guideline</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#further-help" id="id52">Further Help</a></p></li>
<li><p><a class="reference internal" href="#example-of-a-generator" id="id53">Example of a Generator</a></p></li>
<li><p><a class="reference internal" href="#frontend-typescript-code-style-guide-recommendations" id="id54">Frontend Typescript Code Style Guide Recommendations</a></p></li>
<li><p><a class="reference internal" href="#frontend-components" id="id55">Frontend components</a></p></li>
<li><p><a class="reference internal" href="#helper" id="id56">Helper</a></p></li>
<li><p><a class="reference internal" href="#terminology-and-wording" id="id57">Terminology and wording</a></p></li>
<li><p><a class="reference internal" href="#frontend-branding" id="id58">Frontend branding</a></p></li>
<li><p><a class="reference internal" href="#ui-style-guide" id="id59">UI Style Guide</a></p>
<ul>
<li><p><a class="reference internal" href="#colors" id="id60">Colors</a></p></li>
<li><p><a class="reference internal" href="#buttons" id="id61">Buttons</a></p></li>
<li><p><a class="reference internal" href="#links" id="id62">Links</a></p></li>
<li><p><a class="reference internal" href="#forms" id="id63">Forms</a></p></li>
<li><p><a class="reference internal" href="#modals" id="id64">Modals</a></p></li>
<li><p><a class="reference internal" href="#icons" id="id65">Icons</a></p></li>
<li><p><a class="reference internal" href="#navigation" id="id66">Navigation</a></p></li>
<li><p><a class="reference internal" href="#alerts-and-notifications" id="id67">Alerts and notifications</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#error-handling" id="id68">Error Handling</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#internationalization-i18n" id="id69">Internationalization (i18n)</a></p>
<ul>
<li><p><a class="reference internal" href="#how-to-extract-messages-from-source-code" id="id70">How to extract messages from source code?</a></p></li>
<li><p><a class="reference internal" href="#supported-languages" id="id71">Supported languages</a></p></li>
<li><p><a class="reference internal" href="#translating-process" id="id72">Translating process</a></p></li>
<li><p><a class="reference internal" href="#updating-translated-messages" id="id73">Updating translated messages</a></p></li>
<li><p><a class="reference internal" href="#add-a-new-release-resource-to-transifex" id="id74">Add a new release resource to transifex</a></p></li>
<li><p><a class="reference internal" href="#suggestions" id="id75">Suggestions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#accessibility" id="id76">Accessibility</a></p>
<ul>
<li><p><a class="reference internal" href="#summary" id="id77">Summary</a></p></li>
<li><p><a class="reference internal" href="#accessibility-checkers" id="id78">Accessibility checkers</a></p></li>
<li><p><a class="reference internal" href="#color-contrast-checkers" id="id79">Color contrast checkers</a></p></li>
<li><p><a class="reference internal" href="#accessibility-linters" id="id80">Accessibility linters</a></p></li>
<li><p><a class="reference internal" href="#accessibility-testing" id="id81">Accessibility testing</a></p></li>
<li><p><a class="reference internal" href="#additional-guidelines" id="id82">Additional guidelines</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#backend-development" id="id83">Backend Development</a></p>
<ul>
<li><p><a class="reference internal" href="#unit-testing" id="id84">Unit Testing</a></p></li>
<li><p><a class="reference internal" href="#unit-tests-based-on-tox" id="id85">Unit tests based on tox</a></p></li>
<li><p><a class="reference internal" href="#api-tests-based-on-teuthology" id="id86">API tests based on Teuthology</a></p></li>
<li><p><a class="reference internal" href="#how-to-add-a-new-controller" id="id87">How to add a new controller?</a></p></li>
<li><p><a class="reference internal" href="#implementing-proxy-controller" id="id88">Implementing Proxy Controller</a></p></li>
<li><p><a class="reference internal" href="#how-does-the-restcontroller-work" id="id89">How does the RESTController work?</a></p></li>
<li><p><a class="reference internal" href="#how-to-use-a-custom-api-endpoint-in-a-restcontroller" id="id90">How to use a custom API endpoint in a RESTController?</a></p></li>
<li><p><a class="reference internal" href="#how-to-restrict-access-to-a-controller" id="id91">How to restrict access to a controller?</a></p></li>
<li><p><a class="reference internal" href="#how-to-create-a-dedicated-ui-endpoint-which-uses-the-public-api" id="id92">How to create a dedicated UI endpoint which uses the ‘public’ API?</a></p></li>
<li><p><a class="reference internal" href="#how-to-access-the-manager-module-instance-from-a-controller" id="id93">How to access the manager module instance from a controller?</a></p></li>
<li><p><a class="reference internal" href="#how-to-write-a-unit-test-for-a-controller" id="id94">How to write a unit test for a controller?</a></p></li>
<li><p><a class="reference internal" href="#how-to-update-or-create-new-dashboards-in-grafana" id="id95">How to update or create new dashboards in grafana?</a></p></li>
<li><p><a class="reference internal" href="#how-to-listen-for-manager-notifications-in-a-controller" id="id96">How to listen for manager notifications in a controller?</a></p></li>
<li><p><a class="reference internal" href="#how-to-write-a-unit-test-when-a-controller-accesses-a-ceph-module" id="id97">How to write a unit test when a controller accesses a Ceph module?</a></p></li>
<li><p><a class="reference internal" href="#how-to-add-a-new-configuration-setting" id="id98">How to add a new configuration setting?</a></p></li>
<li><p><a class="reference internal" href="#how-to-run-a-controller-read-write-operation-asynchronously" id="id99">How to run a controller read-write operation asynchronously?</a></p></li>
<li><p><a class="reference internal" href="#how-to-get-the-list-of-executing-and-finished-asynchronous-tasks" id="id100">How to get the list of executing and finished asynchronous tasks?</a></p></li>
<li><p><a class="reference internal" href="#how-to-use-asynchronous-apis-with-asynchronous-tasks" id="id101">How to use asynchronous APIs with asynchronous tasks?</a></p></li>
<li><p><a class="reference internal" href="#how-to-update-the-execution-progress-of-an-asynchronous-task" id="id102">How to update the execution progress of an asynchronous task?</a></p></li>
<li><p><a class="reference internal" href="#how-to-deal-with-asynchronous-tasks-in-the-front-end" id="id103">How to deal with asynchronous tasks in the front-end?</a></p></li>
<li><p><a class="reference internal" href="#rest-api-documentation" id="id104">REST API documentation</a></p></li>
<li><p><a class="reference internal" href="#error-handling-in-python" id="id105">Error Handling in Python</a></p></li>
<li><p><a class="reference internal" href="#plug-ins" id="id106">Plug-ins</a></p></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
<section id="feature-design">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Feature Design</a><a class="headerlink" href="#feature-design" title="Permalink to this heading"></a></h2>
<p>To promote collaboration on new Ceph Dashboard features, the first step is
the definition of a design document. These documents then form the basis of
implementation scope and permit wider participation in the evolution of the
Ceph Dashboard UI.</p>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Design Documents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../dashboard/ui_goals/"> UI Design Goals</a></li>
</ul>
</div>
</section>
<section id="preliminary-steps">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Preliminary Steps</a><a class="headerlink" href="#preliminary-steps" title="Permalink to this heading"></a></h2>
<p>The following documentation chapters expect a running Ceph cluster and at
least a running <code class="docutils literal notranslate"><span class="pre">dashboard</span></code> manager module (with few exceptions). This
chapter gives an introduction on how to set up such a system for development,
without the need to set up a full-blown production environment. All options
introduced in this chapter are based on a so called <code class="docutils literal notranslate"><span class="pre">vstart</span></code> environment.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Every <code class="docutils literal notranslate"><span class="pre">vstart</span></code> environment needs Ceph <a class="reference external" href="https://docs.ceph.com/docs/master/install/build-ceph/">to be compiled</a> from its GitHub
repository, though Docker environments simplify that step by providing a
shell script that contains those instructions.</p>
<p>One exception to this rule are the <a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev#quick-install-rpm-based">build-free</a> capabilities of
<a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev">ceph-dev</a>. See below for more information.</p>
</div>
<section id="vstart">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">vstart</a><a class="headerlink" href="#vstart" title="Permalink to this heading"></a></h3>
<p>“vstart” is actually a shell script in the <code class="docutils literal notranslate"><span class="pre">src/</span></code> directory of the Ceph
repository (<code class="docutils literal notranslate"><span class="pre">src/vstart.sh</span></code>). It is used to start a single node Ceph
cluster on the machine where it is executed. Several required and some
optional Ceph internal services are started automatically when it is used to
start a Ceph cluster. vstart is the basis for the three most commonly used
development environments in Ceph Dashboard.</p>
<p>You can read more about vstart in <a class="reference internal" href="../../dev_cluster_deployment/#dev-deploying-a-development-cluster"><span class="std std-ref">Deploying a development cluster</span></a>. Additional information for developers
can also be found in the <a class="reference external" href="https://docs.ceph.com/docs/master/dev/quick_guide/">Developer Guide</a>.</p>
</section>
<section id="host-based-vs-docker-based-development-environments">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">Host-based vs Docker-based Development Environments</a><a class="headerlink" href="#host-based-vs-docker-based-development-environments" title="Permalink to this heading"></a></h3>
<p>This document introduces you to three different development environments, all
based on vstart. Those are:</p>
<ul>
<li><p>vstart running on your host system</p></li>
<li><p>vstart running in a Docker environment</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ricardoasmarques/ceph-dev-docker">ceph-dev-docker</a></p></li>
<li><p><a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev">ceph-dev</a></p></li>
</ul>
<p>Besides their independent development branches and sometimes slightly
different approaches, they also differ with respect to their underlying
operating systems.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Release</p></th>
<th class="head"><p>ceph-dev-docker</p></th>
<th class="head"><p>ceph-dev</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Mimic</p></td>
<td><p>openSUSE Leap 15</p></td>
<td><p>CentOS 7</p></td>
</tr>
<tr class="row-odd"><td><p>Nautilus</p></td>
<td><p>openSUSE Leap 15</p></td>
<td><p>CentOS 7</p></td>
</tr>
<tr class="row-even"><td><p>Octopus</p></td>
<td><p>openSUSE Leap 15.2</p></td>
<td><p>CentOS 8</p></td>
</tr>
<tr class="row-odd"><td><p>Master</p></td>
<td><p>openSUSE Tumbleweed</p></td>
<td><p>CentOS 8</p></td>
</tr>
</tbody>
</table>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Independently of which of these environments you will choose, you need to
compile Ceph in that environment. If you compiled Ceph on your host system,
you would have to recompile it on Docker to be able to switch to a Docker
based solution. The same is true vice versa. If you previously used a
Docker development environment and compiled Ceph there and you now want to
switch to your host system, you will also need to recompile Ceph (or
compile Ceph using another separate repository).</p>
<p><a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev">ceph-dev</a> is an exception to this rule as one of the options it provides
is <a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev#quick-install-rpm-based">build-free</a>. This is accomplished through a Ceph installation using
RPM system packages. You will still be able to work with a local GitHub
repository like you are used to.</p>
</div>
<section id="development-environment-on-your-host-system">
<h4><a class="toc-backref" href="#id9" role="doc-backlink">Development environment on your host system</a><a class="headerlink" href="#development-environment-on-your-host-system" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>No need to learn or have experience with Docker, jump in right away.</p></li>
<li><p>Limited amount of scripts to support automation (like Ceph compilation).</p></li>
<li><p>No pre-configured easy-to-start services (Prometheus, Grafana, etc).</p></li>
<li><p>Limited amount of host operating systems supported, depending on which
Ceph version is supposed to be used.</p></li>
<li><p>Dependencies need to be installed on your host.</p></li>
<li><p>You might find yourself in the situation where you need to upgrade your
host operating system (for instance due to a change of the GCC version used
to compile Ceph).</p></li>
</ul>
</section>
<section id="development-environments-based-on-docker">
<h4><a class="toc-backref" href="#id10" role="doc-backlink">Development environments based on Docker</a><a class="headerlink" href="#development-environments-based-on-docker" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>Some overhead in learning Docker if you are not used to it yet.</p></li>
<li><p>Both Docker projects provide you with scripts that help you getting started
and automate recurring tasks.</p></li>
<li><p>Both Docker environments come with partly pre-configured external services
which can be used to attach to or complement Ceph Dashboard features, like</p>
<ul>
<li><p>Prometheus</p></li>
<li><p>Grafana</p></li>
<li><p>Node-Exporter</p></li>
<li><p>Shibboleth</p></li>
<li><p>HAProxy</p></li>
</ul>
</li>
<li><p>Works independently of the operating system you use on your host.</p></li>
</ul>
</section>
</section>
<section id="vstart-on-your-host-system">
<h3><a class="toc-backref" href="#id11" role="doc-backlink">vstart on your host system</a><a class="headerlink" href="#vstart-on-your-host-system" title="Permalink to this heading"></a></h3>
<p>The vstart script is usually called from your <cite>build/</cite> directory like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">../</span><span class="n">src</span><span class="o">/</span><span class="n">vstart</span><span class="o">.</span><span class="n">sh</span> <span class="o">-</span><span class="n">n</span> <span class="o">-</span><span class="n">d</span>
</pre></div>
</div>
<p>In this case <code class="docutils literal notranslate"><span class="pre">-n</span></code> ensures that a new vstart cluster is created and that a
possibly previously created cluster isn’t re-used. <code class="docutils literal notranslate"><span class="pre">-d</span></code> enables debug
messages in log files. There are several more options to chose from. You can
get a list using the <code class="docutils literal notranslate"><span class="pre">--help</span></code> argument.</p>
<p>At the end of the output of vstart, there should be information about the
dashboard and its URLs:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vstart</span> <span class="n">cluster</span> <span class="n">complete</span><span class="o">.</span> <span class="n">Use</span> <span class="n">stop</span><span class="o">.</span><span class="n">sh</span> <span class="n">to</span> <span class="n">stop</span><span class="o">.</span> <span class="n">See</span> <span class="n">out</span><span class="o">/*</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span> <span class="s1">&#39;tail -f out/????&#39;</span><span class="p">)</span> <span class="k">for</span> <span class="n">debug</span> <span class="n">output</span><span class="o">.</span>

<span class="n">dashboard</span> <span class="n">urls</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="mf">192.168.178.84</span><span class="p">:</span><span class="mi">41259</span><span class="p">,</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="mf">192.168.178.84</span><span class="p">:</span><span class="mi">43259</span><span class="p">,</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="mf">192.168.178.84</span><span class="p">:</span><span class="mi">45259</span>
  <span class="n">w</span><span class="o">/</span> <span class="n">user</span><span class="o">/</span><span class="k">pass</span><span class="p">:</span> <span class="n">admin</span> <span class="o">/</span> <span class="n">admin</span>
</pre></div>
</div>
<p>During development (especially in backend development), you also want to
check on occasions if the dashboard manager module is still running. To do so
you can call <cite>./bin/ceph mgr services</cite> manually. It will list all the URLs of
successfully enabled services. Only URLs of services which are available over
HTTP(S) will be listed there. Ceph Dashboard is one of these services. It
should look similar to the following output:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./bin/ceph mgr services
{
    &quot;dashboard&quot;: &quot;https://home:41931/&quot;
}
</pre></div>
</div>
<p>By default, this environment uses a randomly chosen port for Ceph Dashboard
and you need to use this command to find out which one it has become.</p>
</section>
<section id="docker">
<h3><a class="toc-backref" href="#id12" role="doc-backlink">Docker</a><a class="headerlink" href="#docker" title="Permalink to this heading"></a></h3>
<p>Docker development environments usually ship with a lot of useful scripts.
<code class="docutils literal notranslate"><span class="pre">ceph-dev-docker</span></code> for instance contains a file called <cite>start-ceph.sh</cite>,
which cleans up log files, always starts a Rados Gateway service, sets some
Ceph Dashboard configuration options and automatically runs a frontend proxy,
all before or after starting up your vstart cluster.</p>
<p>Instructions on how to use those environments are contained in their
respective repository README files.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ricardoasmarques/ceph-dev-docker">ceph-dev-docker</a></p></li>
<li><p><a class="reference external" href="https://github.com/rhcs-dashboard/ceph-dev">ceph-dev</a></p></li>
</ul>
</section>
</section>
<section id="frontend-development">
<h2><a class="toc-backref" href="#id13" role="doc-backlink">Frontend Development</a><a class="headerlink" href="#frontend-development" title="Permalink to this heading"></a></h2>
<p>Before you can start the dashboard from within a development environment, you
will need to generate the frontend code and either use a compiled and running
Ceph cluster (e.g. started by <code class="docutils literal notranslate"><span class="pre">vstart.sh</span></code>) or the standalone development web
server.</p>
<p>The build process is based on <a class="reference external" href="https://nodejs.org/">Node.js</a> and requires the
<a class="reference external" href="https://www.npmjs.com/">Node Package Manager</a> <code class="docutils literal notranslate"><span class="pre">npm</span></code> to be installed.</p>
<section id="prerequisites">
<h3><a class="toc-backref" href="#id14" role="doc-backlink">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h3>
<blockquote>
<div><ul class="simple">
<li><p>Node 20.13.1 or higher</p></li>
<li><p>NPM 10.5.2 or higher</p></li>
</ul>
</div></blockquote>
<dl>
<dt>nodeenv:</dt><dd><p>During Ceph’s build we create a virtualenv with <code class="docutils literal notranslate"><span class="pre">node</span></code> and <code class="docutils literal notranslate"><span class="pre">npm</span></code>
installed, which can be used as an alternative to installing node/npm in your
system.</p>
<p>If you want to use the node installed in the virtualenv you just need to
activate the virtualenv before you run any npm commands. To activate it run
<code class="docutils literal notranslate"><span class="pre">.</span> <span class="pre">build/src/pybind/mgr/dashboard/node-env/bin/activate</span></code>.</p>
<p>Once you finish, you can simply run <code class="docutils literal notranslate"><span class="pre">deactivate</span></code> and exit the virtualenv.</p>
</dd>
<dt>Angular CLI:</dt><dd><p>If you do not have the <a class="reference external" href="https://github.com/angular/angular-cli">Angular CLI</a>
installed globally, then you need to execute <code class="docutils literal notranslate"><span class="pre">ng</span></code> commands with an
additional <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span></code> before it.</p>
</dd>
</dl>
</section>
<section id="package-installation">
<h3><a class="toc-backref" href="#id15" role="doc-backlink">Package installation</a><a class="headerlink" href="#package-installation" title="Permalink to this heading"></a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">ci</span></code> in directory <code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend</span></code> to
install the required packages locally.</p>
</section>
<section id="adding-or-updating-packages">
<h3><a class="toc-backref" href="#id16" role="doc-backlink">Adding or updating packages</a><a class="headerlink" href="#adding-or-updating-packages" title="Permalink to this heading"></a></h3>
<p>Run the following commands to add/update a package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">npm</span> <span class="n">install</span> <span class="o">&lt;</span><span class="n">PACKAGE_NAME</span><span class="o">&gt;</span>
<span class="n">npm</span> <span class="n">ci</span>
</pre></div>
</div>
</section>
<section id="setting-up-a-development-server">
<h3><a class="toc-backref" href="#id17" role="doc-backlink">Setting up a Development Server</a><a class="headerlink" href="#setting-up-a-development-server" title="Permalink to this heading"></a></h3>
<p>Create the <code class="docutils literal notranslate"><span class="pre">proxy.conf.json</span></code> file based on <code class="docutils literal notranslate"><span class="pre">proxy.conf.json.sample</span></code>.</p>
<p>Run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">start</span></code> for a dev server.
Navigate to <code class="docutils literal notranslate"><span class="pre">http://localhost:4200/</span></code>. The app will automatically
reload if you change any of the source files.</p>
</section>
<section id="code-scaffolding">
<h3><a class="toc-backref" href="#id18" role="doc-backlink">Code Scaffolding</a><a class="headerlink" href="#code-scaffolding" title="Permalink to this heading"></a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">ng</span> <span class="pre">generate</span> <span class="pre">component</span> <span class="pre">component-name</span></code> to generate a new
component. You can also use
<code class="docutils literal notranslate"><span class="pre">ng</span> <span class="pre">generate</span> <span class="pre">directive|pipe|service|class|guard|interface|enum|module</span></code>.</p>
</section>
<section id="build-the-project">
<h3><a class="toc-backref" href="#id19" role="doc-backlink">Build the Project</a><a class="headerlink" href="#build-the-project" title="Permalink to this heading"></a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">build</span></code> to build the project. The build artifacts will be
stored in the <code class="docutils literal notranslate"><span class="pre">dist/</span></code> directory. Use the <code class="docutils literal notranslate"><span class="pre">--prod</span></code> flag for a
production build (<code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">build</span> <span class="pre">--</span> <span class="pre">--prod</span></code>). Navigate to <code class="docutils literal notranslate"><span class="pre">https://localhost:8443</span></code>.</p>
</section>
<section id="build-the-code-documentation">
<h3><a class="toc-backref" href="#id20" role="doc-backlink">Build the Code Documentation</a><a class="headerlink" href="#build-the-code-documentation" title="Permalink to this heading"></a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">doc-build</span></code> to generate code docs in the <code class="docutils literal notranslate"><span class="pre">documentation/</span></code>
directory. To make them accessible locally for a web browser, run
<code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">doc-serve</span></code> and they will become available at <code class="docutils literal notranslate"><span class="pre">http://localhost:8444</span></code>.
With <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">compodoc</span> <span class="pre">--</span> <span class="pre">&lt;opts&gt;</span></code> you may
<a class="reference external" href="https://compodoc.app/guides/usage.html">fully configure it</a>.</p>
</section>
<section id="code-linting-and-formatting">
<h3><a class="toc-backref" href="#id21" role="doc-backlink">Code linting and formatting</a><a class="headerlink" href="#code-linting-and-formatting" title="Permalink to this heading"></a></h3>
<p>We use the following tools to lint and format the code in all our TS, SCSS and
HTML files:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://codelyzer.com/">codelyzer</a></p></li>
<li><p><a class="reference external" href="https://github.com/chinchiheather/html-linter">html-linter</a></p></li>
<li><p><a class="reference external" href="https://github.com/htmllint/htmllint-cli">htmllint-cli</a></p></li>
<li><p><a class="reference external" href="https://prettier.io/">Prettier</a></p></li>
<li><p><a class="reference external" href="https://eslint.org/">ESLint</a></p></li>
<li><p><a class="reference external" href="https://stylelint.io/">stylelint</a></p></li>
</ul>
<p>We added 2 npm scripts to help run these tools:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">lint</span></code>, will check frontend files against all linters</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">fix</span></code>, will try to fix all the detected linting errors</p></li>
</ul>
</section>
<section id="ceph-dashboard-and-bootstrap">
<h3><a class="toc-backref" href="#id22" role="doc-backlink">Ceph Dashboard and Bootstrap</a><a class="headerlink" href="#ceph-dashboard-and-bootstrap" title="Permalink to this heading"></a></h3>
<p>Currently we are using Bootstrap on the Ceph Dashboard as a CSS framework. This means that most of our SCSS and HTML
code can make use of all the utilities and other advantages Bootstrap is offering. In the past we often have used our
own custom styles and this lead to more and more variables with a single use and double defined variables which
sometimes are forgotten to be removed or it led to styling be inconsistent because people forgot to change a color or to
adjust a custom SCSS class.</p>
<p>To get the current version of Bootstrap used inside Ceph please refer to the <code class="docutils literal notranslate"><span class="pre">package.json</span></code> and search for:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">bootstrap</span></code>: For the Bootstrap version used.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&#64;ng-bootstrap</span></code>: For the version of the Angular bindings which we are using.</p></li>
</ul>
<p>So for the future please do the following when visiting a component:</p>
<ul class="simple">
<li><p>Does this HTML/SCSS code use custom code? - If yes: Is it needed? --&gt; Clean it up before changing the things you want
to fix or change.</p></li>
<li><p>If you are creating a new component: Please make use of Bootstrap as much as reasonably possible! Don’t try to
reinvent the wheel.</p></li>
<li><p>If possible please look up if Bootstrap has guidelines on how to extend it properly to do achieve what you want to
achieve.</p></li>
</ul>
<p>The more bootstrap alike our code is the easier it is to theme, to maintain and the less bugs we will have. Also since
Bootstrap is a framework which tries to have usability and user experience in mind we increase both points
exponentially. The biggest benefit of all is that there is less code for us to maintain which makes it easier to read
for beginners and even more easy for people how are already familiar with the code.</p>
</section>
<section id="writing-unit-tests">
<h3><a class="toc-backref" href="#id23" role="doc-backlink">Writing Unit Tests</a><a class="headerlink" href="#writing-unit-tests" title="Permalink to this heading"></a></h3>
<p>To write unit tests most efficient we have a small collection of tools,
we use within test suites.</p>
<p>Those tools can be found under
<code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend/src/testing/</span></code>, especially take
a look at <code class="docutils literal notranslate"><span class="pre">unit-test-helper.ts</span></code>.</p>
<p>There you will be able to find:</p>
<p><code class="docutils literal notranslate"><span class="pre">configureTestBed</span></code> that replaces the initial <code class="docutils literal notranslate"><span class="pre">TestBed</span></code>
methods. It takes the same arguments as <code class="docutils literal notranslate"><span class="pre">TestBed.configureTestingModule</span></code>.
Using it will run your tests a lot faster in development, as it doesn’t
recreate everything from scratch on every test. To use the default behaviour
pass <code class="docutils literal notranslate"><span class="pre">true</span></code> as the second argument.</p>
<p><code class="docutils literal notranslate"><span class="pre">PermissionHelper</span></code> to help determine if
the correct actions are shown based on the current permissions and selection
in a list.</p>
<p><code class="docutils literal notranslate"><span class="pre">FormHelper</span></code> which makes testing a form a lot easier
with a few simple methods. It allows you to set a control or multiple
controls, expect if a control is valid or has an error or just do both with
one method. Additional you can expect a template element or multiple elements
to be visible in the rendered template.</p>
</section>
<section id="running-unit-tests">
<h3><a class="toc-backref" href="#id24" role="doc-backlink">Running Unit Tests</a><a class="headerlink" href="#running-unit-tests" title="Permalink to this heading"></a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">test</span></code> to execute the unit tests via <a class="reference external" href="https://facebook.github.io/jest/">Jest</a>.</p>
<p>If you get errors on all tests, it could be because <a class="reference external" href="https://facebook.github.io/jest/">Jest</a> or something else was updated.
There are a few ways how you can try to resolve this:</p>
<ul class="simple">
<li><p>Remove all modules with <code class="docutils literal notranslate"><span class="pre">rm</span> <span class="pre">-rf</span> <span class="pre">dist</span> <span class="pre">node_modules</span></code> and run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">install</span></code>
again in order to reinstall them</p></li>
<li><p>Clear the cache of jest by running <code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">jest</span> <span class="pre">--clearCache</span></code></p></li>
</ul>
</section>
<section id="running-end-to-end-e2e-tests">
<h3><a class="toc-backref" href="#id25" role="doc-backlink">Running End-to-End (E2E) Tests</a><a class="headerlink" href="#running-end-to-end-e2e-tests" title="Permalink to this heading"></a></h3>
<p>We use <a class="reference external" href="https://www.cypress.io/">Cypress</a> to run our frontend E2E tests.</p>
<section id="e2e-prerequisites">
<h4><a class="toc-backref" href="#id26" role="doc-backlink">E2E Prerequisites</a><a class="headerlink" href="#e2e-prerequisites" title="Permalink to this heading"></a></h4>
<p>You need to previously build the frontend.</p>
<p>In some environments, depending on your user permissions and the CYPRESS_CACHE_FOLDER,
you might need to run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">ci</span></code> with the <code class="docutils literal notranslate"><span class="pre">--unsafe-perm</span></code> flag.</p>
<p>You might need to install additional packages to be able to run Cypress.
Please run <code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">verify</span></code> to verify it.</p>
</section>
<section id="run-frontend-e2e-tests-sh">
<h4><a class="toc-backref" href="#id27" role="doc-backlink">run-frontend-e2e-tests.sh</a><a class="headerlink" href="#run-frontend-e2e-tests-sh" title="Permalink to this heading"></a></h4>
<p>Our <code class="docutils literal notranslate"><span class="pre">run-frontend-e2e-tests.sh</span></code> script is the go to solution when you wish to
do a full scale e2e run.
It will verify if everything needed is installed, start a new vstart cluster
and run the full test suite.</p>
<p>Start all frontend E2E tests with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd src/pybind/mgr/dashboard
$ ./run-frontend-e2e-tests.sh
</pre></div>
</div>
<dl>
<dt>Report:</dt><dd><p>You can follow the e2e report on the terminal and you can find the screenshots
of failed test cases by opening the following directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src</span><span class="o">/</span><span class="n">pybind</span><span class="o">/</span><span class="n">mgr</span><span class="o">/</span><span class="n">dashboard</span><span class="o">/</span><span class="n">frontend</span><span class="o">/</span><span class="n">cypress</span><span class="o">/</span><span class="n">screenshots</span><span class="o">/</span>
</pre></div>
</div>
</dd>
<dt>Device:</dt><dd><p>You can force the script to use a specific device with the <code class="docutils literal notranslate"><span class="pre">-d</span></code> flag:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./run-frontend-e2e-tests.sh -d &lt;chrome|chromium|electron|docker&gt;
</pre></div>
</div>
</dd>
<dt>Remote:</dt><dd><p>By default this script will stop and start a new vstart cluster.
If you want to run the tests outside the ceph environment, you will need to
manually define the dashboard url using <code class="docutils literal notranslate"><span class="pre">-r</span></code> and, optionally, credentials
(<code class="docutils literal notranslate"><span class="pre">-u</span></code>, <code class="docutils literal notranslate"><span class="pre">-p</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./run-frontend-e2e-tests.sh -r &lt;DASHBOARD_URL&gt; -u &lt;E2E_LOGIN_USER&gt; -p &lt;E2E_LOGIN_PWD&gt;
</pre></div>
</div>
</dd>
<dt>Note:</dt><dd><p>When using docker, as your device, you might need to run the script with sudo
permissions.</p>
</dd>
</dl>
</section>
<section id="run-cephadm-e2e-tests-sh">
<h4><a class="toc-backref" href="#id28" role="doc-backlink">run-cephadm-e2e-tests.sh</a><a class="headerlink" href="#run-cephadm-e2e-tests-sh" title="Permalink to this heading"></a></h4>
<p><code class="docutils literal notranslate"><span class="pre">run-cephadm-e2e-tests.sh</span></code> runs a subset of E2E tests to verify that the Dashboard and cephadm as
Orchestrator backend behave correctly.</p>
<p>Prerequisites: you need to install <a class="reference external" href="https://kcli.readthedocs.io/en/latest/">KCLI</a> and Node.js in your local machine.</p>
<p>Configure KCLI plan requirements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo chown -R $(id -un) /var/lib/libvirt/images
$ mkdir -p /var/lib/libvirt/images/ceph-dashboard
$ kcli create pool -p /var/lib/libvirt/images/ceph-dashboard ceph-dashboard
$ kcli create network -c 192.168.100.0/24 ceph-dashboard
</pre></div>
</div>
<dl class="simple">
<dt>Note:</dt><dd><p>This script is aimed to be run as jenkins job so the cleanup is triggered only in a jenkins
environment. In local, the user will shutdown the cluster when desired (i.e. after debugging).</p>
</dd>
</dl>
<p>Start E2E tests by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd &lt;your/ceph/repo/dir&gt;
$ sudo chown -R $(id -un) src/pybind/mgr/dashboard/frontend/{dist,node_modules,src/environments}
$ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh
</pre></div>
</div>
<dl>
<dt>Note:</dt><dd><p>In fedora 35, there can occur a permission error when trying to mount the shared_folders. This can be
fixed by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo setfacl -R -m u:qemu:rwx &lt;abs-path-to-your-user-home&gt;
</pre></div>
</div>
<p>or also by setting the appropriate permission to your $HOME directory</p>
</dd>
</dl>
<p>You can also start a cluster in development mode (so the frontend build starts in watch mode and you
only have to reload the page for the changes to be reflected) by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./src/pybind/mgr/dashboard/ci/cephadm/start-cluster.sh --dev-mode
</pre></div>
</div>
<dl class="simple">
<dt>Note:</dt><dd><p>Add <code class="docutils literal notranslate"><span class="pre">--expanded</span></code> if you need a cluster ready to deploy services (one with enough monitor
daemons spread across different hosts and enough OSDs).</p>
</dd>
</dl>
<p>Test your changes by running:</p>
<blockquote>
<div><p>$ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh</p>
</div></blockquote>
<p>Shutdown the cluster by running:</p>
<blockquote>
<div><p>$ kcli delete plan -y ceph
$ # In development mode, also kill the npm build watch process (e.g., pkill -f “ng build”)</p>
</div></blockquote>
</section>
<section id="other-running-options">
<h4><a class="toc-backref" href="#id29" role="doc-backlink">Other running options</a><a class="headerlink" href="#other-running-options" title="Permalink to this heading"></a></h4>
<p>During active development, it is not recommended to run the previous script,
as it is not prepared for constant file changes.
Instead you should use one of the following commands:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">e2e</span></code> - This will run <code class="docutils literal notranslate"><span class="pre">ng</span> <span class="pre">serve</span></code> and open the Cypress Test Runner.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">run</span> <span class="pre">e2e:ci</span></code> - This will run <code class="docutils literal notranslate"><span class="pre">ng</span> <span class="pre">serve</span></code> and run the Cypress Test Runner once.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">run</span></code> - This calls cypress directly and will run the Cypress Test Runner.
You need to have a running frontend server.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">open</span></code> - This calls cypress directly and will open the Cypress Test Runner.
You need to have a running frontend server.</p></li>
</ul>
<p>Calling Cypress directly has the advantage that you can use any of the available
<a class="reference external" href="https://docs.cypress.io/guides/guides/command-line.html#cypress-run">flags</a>
to customize your test run and you don’t need to start a frontend server each time.</p>
<p>Using one of the <code class="docutils literal notranslate"><span class="pre">open</span></code> commands, will open a cypress application where you
can see all the test files you have and run each individually.
This is going to be run in watch mode, so if you make any changes to test files,
it will retrigger the test run.
This cannot be used inside docker, as it requires X11 environment to be able to open.</p>
<p>By default Cypress will look for the web page at <code class="docutils literal notranslate"><span class="pre">https://localhost:4200/</span></code>.
If you are serving it in a different URL you will need to configure it by
exporting the environment variable CYPRESS_BASE_URL with the new value.
E.g.: <code class="docutils literal notranslate"><span class="pre">CYPRESS_BASE_URL=https://localhost:41076/</span> <span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">open</span></code></p>
</section>
<section id="cypress-cache-folder">
<h4><a class="toc-backref" href="#id30" role="doc-backlink">CYPRESS_CACHE_FOLDER</a><a class="headerlink" href="#cypress-cache-folder" title="Permalink to this heading"></a></h4>
<p>When installing cypress via npm, a binary of the cypress app will also be
downloaded and stored in a cache folder.
This removes the need to download it every time you run <code class="docutils literal notranslate"><span class="pre">npm</span> <span class="pre">ci</span></code> or even when
using cypress in a separate project.</p>
<p>By default Cypress uses ~/.cache to store the binary.
To prevent changes to the user home directory, we have changed this folder to
<code class="docutils literal notranslate"><span class="pre">/ceph/build/src/pybind/mgr/dashboard/cypress</span></code>, so when you build ceph or run
<code class="docutils literal notranslate"><span class="pre">run-frontend-e2e-tests.sh</span></code> this is the directory Cypress will use.</p>
<p>When using any other command to install or run cypress,
it will go back to the default directory. It is recommended that you export the
CYPRESS_CACHE_FOLDER environment variable with a fixed directory, so you always
use the same directory no matter which command you use.</p>
</section>
</section>
<section id="writing-end-to-end-tests">
<h3><a class="toc-backref" href="#id31" role="doc-backlink">Writing End-to-End Tests</a><a class="headerlink" href="#writing-end-to-end-tests" title="Permalink to this heading"></a></h3>
<section id="the-pagerhelper-class">
<h4><a class="toc-backref" href="#id32" role="doc-backlink">The PagerHelper class</a><a class="headerlink" href="#the-pagerhelper-class" title="Permalink to this heading"></a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">PageHelper</span></code> class is supposed to be used for general purpose code that
can be used on various pages or suites.</p>
<p>Examples are</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">navigateTo()</span></code> - Navigates to a specific page and waits for it to load</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">getFirstTableCell()</span></code> - returns the first table cell. You can also pass a
string with the desired content and it will return the first cell that
contains it.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">getTabsCount()</span></code> - returns the amount of tabs</p></li>
</ul>
<p>Every method that could be useful on several pages belongs there. Also, methods
which enhance the derived classes of the PageHelper belong there. A good
example for such a case is the <code class="docutils literal notranslate"><span class="pre">restrictTo()</span></code> decorator. It ensures that a
method implemented in a subclass of PageHelper is called on the correct page.
It will also show a developer-friendly warning if this is not the case.</p>
</section>
<section id="subclasses-of-pagehelper">
<h4><a class="toc-backref" href="#id33" role="doc-backlink">Subclasses of PageHelper</a><a class="headerlink" href="#subclasses-of-pagehelper" title="Permalink to this heading"></a></h4>
<section id="helper-methods">
<h5><a class="toc-backref" href="#id34" role="doc-backlink">Helper Methods</a><a class="headerlink" href="#helper-methods" title="Permalink to this heading"></a></h5>
<p>In order to make code reusable which is specific for a particular suite, make
sure to put it in a derived class of the <code class="docutils literal notranslate"><span class="pre">PageHelper</span></code>. For instance, when
talking about the pool suite, such methods would be <code class="docutils literal notranslate"><span class="pre">create()</span></code>, <code class="docutils literal notranslate"><span class="pre">exist()</span></code>
and <code class="docutils literal notranslate"><span class="pre">delete()</span></code>. These methods are specific to a pool but are useful for other
suites.</p>
<p>Methods that return HTML elements which can only be found on a specific page,
should be either implemented in the helper methods of the subclass of PageHelper
or as own methods of the subclass of PageHelper.</p>
</section>
<section id="using-pagehelpers">
<h5><a class="toc-backref" href="#id35" role="doc-backlink">Using PageHelpers</a><a class="headerlink" href="#using-pagehelpers" title="Permalink to this heading"></a></h5>
<p>In any suite, an instance of the specific <code class="docutils literal notranslate"><span class="pre">Helper</span></code> class should be
instantiated and called directly.</p>
<div class="highlight-TypeScript notranslate"><div class="highlight"><pre><span></span><span class="kd">const</span><span class="w"> </span><span class="nx">pools</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="nx">PoolPageHelper</span><span class="p">();</span>

<span class="nx">it</span><span class="p">(</span><span class="s1">&#39;should create a pool&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="nx">pools</span><span class="p">.</span><span class="nx">exist</span><span class="p">(</span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="kc">false</span><span class="p">);</span>
<span class="w">  </span><span class="nx">pools</span><span class="p">.</span><span class="nx">navigateTo</span><span class="p">(</span><span class="s1">&#39;create&#39;</span><span class="p">);</span>
<span class="w">  </span><span class="nx">pools</span><span class="p">.</span><span class="nx">create</span><span class="p">(</span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="mf">8</span><span class="p">);</span>
<span class="w">  </span><span class="nx">pools</span><span class="p">.</span><span class="nx">exist</span><span class="p">(</span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="kc">true</span><span class="p">);</span>
<span class="p">});</span>
</pre></div>
</div>
</section>
</section>
<section id="code-style">
<h4><a class="toc-backref" href="#id36" role="doc-backlink">Code Style</a><a class="headerlink" href="#code-style" title="Permalink to this heading"></a></h4>
<p>Please refer to the official <a class="reference external" href="https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Cypress-Can-Be-Simple-Sometimes">Cypress Core Concepts</a>
for a better insight on how to write and structure tests.</p>
<section id="describe-vs-it">
<h5><a class="toc-backref" href="#id37" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">describe()</span></code> vs <code class="docutils literal notranslate"><span class="pre">it()</span></code></a><a class="headerlink" href="#describe-vs-it" title="Permalink to this heading"></a></h5>
<p>Both <code class="docutils literal notranslate"><span class="pre">describe()</span></code> and <code class="docutils literal notranslate"><span class="pre">it()</span></code> are function blocks, meaning that any
executable code necessary for the test can be contained in either block.
However, Typescript scoping rules still apply, therefore any variables declared
in a <code class="docutils literal notranslate"><span class="pre">describe</span></code> are available to the <code class="docutils literal notranslate"><span class="pre">it()</span></code> blocks inside of it.</p>
<p><code class="docutils literal notranslate"><span class="pre">describe()</span></code> typically are containers for tests, allowing you to break tests
into multiple parts. Likewise, any setup that must be made before your tests are
run can be initialized within the <code class="docutils literal notranslate"><span class="pre">describe()</span></code> block. Here is an example:</p>
<div class="highlight-TypeScript notranslate"><div class="highlight"><pre><span></span><span class="nx">describe</span><span class="p">(</span><span class="s1">&#39;create, edit &amp; delete image test&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="kd">const</span><span class="w"> </span><span class="nx">poolName</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;e2e_images_pool&#39;</span><span class="p">;</span>

<span class="w">  </span><span class="nx">before</span><span class="p">(()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">login</span><span class="p">();</span>
<span class="w">    </span><span class="nx">pools</span><span class="p">.</span><span class="nx">navigateTo</span><span class="p">(</span><span class="s1">&#39;create&#39;</span><span class="p">);</span>
<span class="w">    </span><span class="nx">pools</span><span class="p">.</span><span class="nx">create</span><span class="p">(</span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="mf">8</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;rbd&#39;</span><span class="p">);</span>
<span class="w">    </span><span class="nx">pools</span><span class="p">.</span><span class="nx">exist</span><span class="p">(</span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="kc">true</span><span class="p">);</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="nx">beforeEach</span><span class="p">(()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">login</span><span class="p">();</span>
<span class="w">    </span><span class="nx">images</span><span class="p">.</span><span class="nx">navigateTo</span><span class="p">();</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="c1">//...</span>

<span class="p">});</span>
</pre></div>
</div>
<p>As shown, we can initiate the variable <code class="docutils literal notranslate"><span class="pre">poolName</span></code> as well as run commands
before our test suite begins (creating a pool). <code class="docutils literal notranslate"><span class="pre">describe()</span></code> block messages
should include what the test suite is.</p>
<p><code class="docutils literal notranslate"><span class="pre">it()</span></code> blocks typically are parts of an overarching test. They contain the
functionality of the test suite, each performing individual roles.
Here is an example:</p>
<div class="highlight-TypeScript notranslate"><div class="highlight"><pre><span></span><span class="nx">describe</span><span class="p">(</span><span class="s1">&#39;create, edit &amp; delete image test&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="c1">//...</span>

<span class="w">  </span><span class="nx">it</span><span class="p">(</span><span class="s1">&#39;should create image&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">images</span><span class="p">.</span><span class="nx">createImage</span><span class="p">(</span><span class="nx">imageName</span><span class="p">,</span><span class="w"> </span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;1&#39;</span><span class="p">);</span>
<span class="w">    </span><span class="nx">images</span><span class="p">.</span><span class="nx">getFirstTableCell</span><span class="p">(</span><span class="nx">imageName</span><span class="p">).</span><span class="nx">should</span><span class="p">(</span><span class="s1">&#39;exist&#39;</span><span class="p">);</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="nx">it</span><span class="p">(</span><span class="s1">&#39;should edit image&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">images</span><span class="p">.</span><span class="nx">editImage</span><span class="p">(</span><span class="nx">imageName</span><span class="p">,</span><span class="w"> </span><span class="nx">poolName</span><span class="p">,</span><span class="w"> </span><span class="nx">newImageName</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;2&#39;</span><span class="p">);</span>
<span class="w">    </span><span class="nx">images</span><span class="p">.</span><span class="nx">getFirstTableCell</span><span class="p">(</span><span class="nx">newImageName</span><span class="p">).</span><span class="nx">should</span><span class="p">(</span><span class="s1">&#39;exist&#39;</span><span class="p">);</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="c1">//...</span>
<span class="p">});</span>
</pre></div>
</div>
<p>As shown from the previous example, our <code class="docutils literal notranslate"><span class="pre">describe()</span></code> test suite is to create,
edit and delete an image. Therefore, each <code class="docutils literal notranslate"><span class="pre">it()</span></code> completes one of these steps,
one for creating, one for editing, and so on. Likewise, every <code class="docutils literal notranslate"><span class="pre">it()</span></code> blocks
message should be in lowercase and written so long as “it” can be the prefix of
the message. For example, <code class="docutils literal notranslate"><span class="pre">it('edits</span> <span class="pre">the</span> <span class="pre">test</span> <span class="pre">image'</span> <span class="pre">()</span> <span class="pre">=&gt;</span> <span class="pre">...)</span></code> vs.
<code class="docutils literal notranslate"><span class="pre">it('image</span> <span class="pre">edit</span> <span class="pre">test'</span> <span class="pre">()</span> <span class="pre">=&gt;</span> <span class="pre">...)</span></code>. As shown, the first example makes
grammatical sense with <code class="docutils literal notranslate"><span class="pre">it()</span></code> as the prefix whereas the second message does
not. <code class="docutils literal notranslate"><span class="pre">it()</span></code> should describe what the individual test is doing and what it
expects to happen.</p>
</section>
</section>
</section>
<section id="visual-regression-testing">
<h3><a class="toc-backref" href="#id38" role="doc-backlink">Visual Regression Testing</a><a class="headerlink" href="#visual-regression-testing" title="Permalink to this heading"></a></h3>
<p>For visual regression testing, we use <a class="reference external" href="https://applitools.com/products-eyes/">Applitools Eyes</a>
an AI powered automated  visual regression testing tool.
Applitools integrates with our existing Cypress E2E tests.
The tests currently are located at: <code class="docutils literal notranslate"><span class="pre">ceph/src/pybind/mgr/dashboard/frontend/cypress/integration/visualTests</span></code> and
follow the naming convention: <code class="docutils literal notranslate"><span class="pre">&lt;component-name&gt;.vrt-spec.ts</span></code>.</p>
<section id="running-visual-regression-tests-locally">
<h4><a class="toc-backref" href="#id39" role="doc-backlink">Running Visual Regression Tests Locally</a><a class="headerlink" href="#running-visual-regression-tests-locally" title="Permalink to this heading"></a></h4>
<p>To run the tests locally, you’ll need an Applitools API key, if you don’t have one, you can sign up
for a free account. After obtaining the API key, export it as an environment variable: <code class="docutils literal notranslate"><span class="pre">APPLITOOLS_API_KEY</span></code>.</p>
<p>Now you can run the tests like normal cypress E2E tests, using either <code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">open</span></code> or in headless mode by running <code class="docutils literal notranslate"><span class="pre">npx</span> <span class="pre">cypress</span> <span class="pre">run</span></code>.</p>
</section>
<section id="capturing-screenshots">
<h4><a class="toc-backref" href="#id40" role="doc-backlink">Capturing Screenshots</a><a class="headerlink" href="#capturing-screenshots" title="Permalink to this heading"></a></h4>
<p>Baseline screenshots are the screenshots against which checkpoint screenshots
(or the screenshots from your feature branch) will be tested.</p>
<p>To capture baseline screenshots, you can run the tests against the master branch,
and then switch to your feature branch and run the tests again to capture checkpoint screenshots.</p>
<p>Now to see your screenshots, login to applitools.com and on the landing page you’ll be greeted with
applitools eyes test runner, where you can see all your screenshots. And if there’s any visual regression or difference (diff) between your baseline and checkpoint screenshots, they’ll be highlighted with a mask over the diff.</p>
</section>
<section id="writing-more-visual-regression-tests">
<h4><a class="toc-backref" href="#id41" role="doc-backlink">Writing More Visual Regression Tests</a><a class="headerlink" href="#writing-more-visual-regression-tests" title="Permalink to this heading"></a></h4>
<p>Please refer to <a class="reference external" href="https://www.npmjs.com/package/&#64;applitools/eyes-cypress#usage">Applitools’s official cypress sdk documentation</a> to write more tests.</p>
</section>
<section id="visual-regression-tests-in-jenkins">
<h4><a class="toc-backref" href="#id42" role="doc-backlink">Visual Regression Tests In Jenkins</a><a class="headerlink" href="#visual-regression-tests-in-jenkins" title="Permalink to this heading"></a></h4>
<p>Currently, all visual regression tests are being run under <a class="reference external" href="https://jenkins.ceph.com/job/ceph-dashboard-pull-requests">ceph dashboard tests</a> GitHub check in the Jenkins job.</p>
</section>
<section id="accepting-or-rejecting-differences">
<h4><a class="toc-backref" href="#id43" role="doc-backlink">Accepting or Rejecting Differences</a><a class="headerlink" href="#accepting-or-rejecting-differences" title="Permalink to this heading"></a></h4>
<p>Currently, only the ceph dashboard team has read and write access to the applitools test runner. If any differences are reported by the tests, and you want to accept them and update the baseline screenshots, or if the differences are due to a genuine regression you can fail them. To perform the above actions, please follow <a class="reference external" href="https://applitools.com/docs/topics/test-manager/pages/page-test-results/tm-accepting-and-rejecting-steps.html">this</a> guide.</p>
</section>
<section id="debugging-regressions">
<h4><a class="toc-backref" href="#id44" role="doc-backlink">Debugging Regressions</a><a class="headerlink" href="#debugging-regressions" title="Permalink to this heading"></a></h4>
<p>If you’re running the tests locally and regressions are reported, you can take advantage of <a class="reference external" href="https://applitools.com/docs/topics/test-manager/viewers/root-cause-analysis.html">Applitools’s Root Cause Analysis feature</a> to find the cause of the regression.</p>
</section>
</section>
<section id="differences-between-frontend-unit-tests-and-end-to-end-e2e-tests-faq">
<h3><a class="toc-backref" href="#id45" role="doc-backlink">Differences between Frontend Unit Tests and End-to-End (E2E) Tests / FAQ</a><a class="headerlink" href="#differences-between-frontend-unit-tests-and-end-to-end-e2e-tests-faq" title="Permalink to this heading"></a></h3>
<p>General introduction about testing and E2E/unit tests</p>
<section id="what-are-e2e-unit-tests-designed-for">
<h4><a class="toc-backref" href="#id46" role="doc-backlink">What are E2E/unit tests designed for?</a><a class="headerlink" href="#what-are-e2e-unit-tests-designed-for" title="Permalink to this heading"></a></h4>
<p>E2E test:</p>
<p>It requires a fully functional system and tests the interaction of all components
of the application (Ceph, back-end, front-end).
E2E tests are designed to mimic the behavior of the user when interacting with the application
- for example when it comes to workflows like creating/editing/deleting an item.
Also the tests should verify that certain items are displayed as a user would see them
when clicking through the UI (for example a menu entry or a pool that has been
created during a test and the pool and its properties should be displayed in the table).</p>
<p>Angular Unit Tests:</p>
<p>Unit tests, as the name suggests, are tests for smaller units of the code.
Those tests are designed for testing all kinds of Angular components (e.g. services, pipes etc.).
They do not require a connection to the backend, hence those tests are independent of it.
The expected data of the backend is mocked in the frontend and by using this data
the functionality of the frontend can be tested without having to have real data from the backend.
As previously mentioned, data is either mocked or, in a simple case, contains a static input,
a function call and an expected static output.
More complex examples include the state of a component (attributes of the component class),
that define how the output changes according to the given input.</p>
</section>
<section id="which-e2e-unit-tests-are-considered-to-be-valid">
<h4><a class="toc-backref" href="#id47" role="doc-backlink">Which E2E/unit tests are considered to be valid?</a><a class="headerlink" href="#which-e2e-unit-tests-are-considered-to-be-valid" title="Permalink to this heading"></a></h4>
<p>This is not easy to answer, but new tests that are written in the same way as already existing
dashboard tests should generally be considered valid.
Unit tests should focus on the component to be tested.
This is either an Angular component, directive, service, pipe, etc.</p>
<p>E2E tests should focus on testing the functionality of the whole application.
Approximately a third of the overall E2E tests should verify the correctness
of user visible elements.</p>
</section>
<section id="how-should-an-e2e-unit-test-look-like">
<h4><a class="toc-backref" href="#id48" role="doc-backlink">How should an E2E/unit test look like?</a><a class="headerlink" href="#how-should-an-e2e-unit-test-look-like" title="Permalink to this heading"></a></h4>
<p>Unit tests should focus on the described purpose
and shouldn’t try to test other things in the same <cite>it</cite> block.</p>
<p>E2E tests should contain a description that either verifies
the correctness of a user visible element or a complete process
like for example the creation/validation/deletion of a pool.</p>
</section>
<section id="what-should-an-e2e-unit-test-cover">
<h4><a class="toc-backref" href="#id49" role="doc-backlink">What should an E2E/unit test cover?</a><a class="headerlink" href="#what-should-an-e2e-unit-test-cover" title="Permalink to this heading"></a></h4>
<p>E2E tests should mostly, but not exclusively, cover interaction with the backend.
This way the interaction with the backend is utilized to write integration tests.</p>
<p>A unit test should mostly cover critical or complex functionality
of a component (Angular Components, Services, Pipes, Directives, etc).</p>
</section>
<section id="what-should-an-e2e-unit-test-not-cover">
<h4><a class="toc-backref" href="#id50" role="doc-backlink">What should an E2E/unit test NOT cover?</a><a class="headerlink" href="#what-should-an-e2e-unit-test-not-cover" title="Permalink to this heading"></a></h4>
<p>Avoid duplicate testing: do not write E2E tests for what’s already
been covered as frontend-unit tests and vice versa.
It may not be possible to completely avoid an overlap.</p>
<p>Unit tests should not be used to extensively click through components and E2E tests
shouldn’t be used to extensively test a single component of Angular.</p>
</section>
<section id="best-practices-guideline">
<h4><a class="toc-backref" href="#id51" role="doc-backlink">Best practices/guideline</a><a class="headerlink" href="#best-practices-guideline" title="Permalink to this heading"></a></h4>
<p>As a general guideline we try to follow the 70/20/10 approach - 70% unit tests,
20% integration tests and 10% end-to-end tests.
For further information please refer to <a class="reference external" href="https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html">this document</a>
and the included “Testing Pyramid”.</p>
</section>
</section>
<section id="further-help">
<h3><a class="toc-backref" href="#id52" role="doc-backlink">Further Help</a><a class="headerlink" href="#further-help" title="Permalink to this heading"></a></h3>
<p>To get more help on the Angular CLI use <code class="docutils literal notranslate"><span class="pre">ng</span> <span class="pre">help</span></code> or go check out the
<a class="reference external" href="https://github.com/angular/angular-cli/blob/master/README.md">Angular CLI
README</a>.</p>
</section>
<section id="example-of-a-generator">
<h3><a class="toc-backref" href="#id53" role="doc-backlink">Example of a Generator</a><a class="headerlink" href="#example-of-a-generator" title="Permalink to this heading"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create module &#39;Core&#39;</span>
<span class="n">src</span><span class="o">/</span><span class="n">app</span><span class="o">&gt;</span> <span class="n">ng</span> <span class="n">generate</span> <span class="n">module</span> <span class="n">core</span> <span class="o">-</span><span class="n">m</span><span class="o">=</span><span class="n">app</span> <span class="o">--</span><span class="n">routing</span>

<span class="c1"># Create module &#39;Auth&#39; under module &#39;Core&#39;</span>
<span class="n">src</span><span class="o">/</span><span class="n">app</span><span class="o">/</span><span class="n">core</span><span class="o">&gt;</span> <span class="n">ng</span> <span class="n">generate</span> <span class="n">module</span> <span class="n">auth</span> <span class="o">-</span><span class="n">m</span><span class="o">=</span><span class="n">core</span> <span class="o">--</span><span class="n">routing</span>
<span class="ow">or</span><span class="p">,</span> <span class="n">alternatively</span><span class="p">:</span>
<span class="n">src</span><span class="o">/</span><span class="n">app</span><span class="o">&gt;</span> <span class="n">ng</span> <span class="n">generate</span> <span class="n">module</span> <span class="n">core</span><span class="o">/</span><span class="n">auth</span> <span class="o">-</span><span class="n">m</span><span class="o">=</span><span class="n">core</span> <span class="o">--</span><span class="n">routing</span>

<span class="c1"># Create component &#39;Login&#39; under module &#39;Auth&#39;</span>
<span class="n">src</span><span class="o">/</span><span class="n">app</span><span class="o">/</span><span class="n">core</span><span class="o">/</span><span class="n">auth</span><span class="o">&gt;</span> <span class="n">ng</span> <span class="n">generate</span> <span class="n">component</span> <span class="n">login</span> <span class="o">-</span><span class="n">m</span><span class="o">=</span><span class="n">core</span><span class="o">/</span><span class="n">auth</span>
<span class="ow">or</span><span class="p">,</span> <span class="n">alternatively</span><span class="p">:</span>
<span class="n">src</span><span class="o">/</span><span class="n">app</span><span class="o">&gt;</span> <span class="n">ng</span> <span class="n">generate</span> <span class="n">component</span> <span class="n">core</span><span class="o">/</span><span class="n">auth</span><span class="o">/</span><span class="n">login</span> <span class="o">-</span><span class="n">m</span><span class="o">=</span><span class="n">core</span><span class="o">/</span><span class="n">auth</span>
</pre></div>
</div>
</section>
<section id="frontend-typescript-code-style-guide-recommendations">
<h3><a class="toc-backref" href="#id54" role="doc-backlink">Frontend Typescript Code Style Guide Recommendations</a><a class="headerlink" href="#frontend-typescript-code-style-guide-recommendations" title="Permalink to this heading"></a></h3>
<p>Group the imports based on its source and separate them with a blank
line.</p>
<p>The source groups can be either from Angular, external or internal.</p>
<p>Example:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">Component</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">&#39;@angular/core&#39;</span><span class="p">;</span>
<span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">Router</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">&#39;@angular/router&#39;</span><span class="p">;</span>

<span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">ToastrManager</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">&#39;ngx-toastr&#39;</span><span class="p">;</span>

<span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">Credentials</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">&#39;../../../shared/models/credentials.model&#39;</span><span class="p">;</span>
<span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">HostService</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s1">&#39;./services/host.service&#39;</span><span class="p">;</span>
</pre></div>
</div>
</section>
<section id="frontend-components">
<h3><a class="toc-backref" href="#id55" role="doc-backlink">Frontend components</a><a class="headerlink" href="#frontend-components" title="Permalink to this heading"></a></h3>
<p>There are several components that can be reused on different pages.
This components are declared on the components module:
<cite>src/pybind/mgr/dashboard/frontend/src/app/shared/components</cite>.</p>
</section>
<section id="helper">
<h3><a class="toc-backref" href="#id56" role="doc-backlink">Helper</a><a class="headerlink" href="#helper" title="Permalink to this heading"></a></h3>
<p>This component should be used to provide additional information to the user.</p>
<p>Example:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">cd-helper</span><span class="p">&gt;</span>
  Some <span class="p">&lt;</span><span class="nt">strong</span><span class="p">&gt;</span>helper<span class="p">&lt;/</span><span class="nt">strong</span><span class="p">&gt;</span> html text
<span class="p">&lt;/</span><span class="nt">cd-helper</span><span class="p">&gt;</span>
</pre></div>
</div>
</section>
<section id="terminology-and-wording">
<h3><a class="toc-backref" href="#id57" role="doc-backlink">Terminology and wording</a><a class="headerlink" href="#terminology-and-wording" title="Permalink to this heading"></a></h3>
<p>Instead of using the Ceph component names, the approach
suggested is to use the logical/generic names (Block over RBD, Filesystem over
CephFS, Object over RGW). Nevertheless, as Ceph-Dashboard cannot completely hide
the Ceph internals, some Ceph-specific names might remain visible.</p>
<p>Regarding the wording for action labels and other textual elements (form titles,
buttons, etc.), the chosen approach is to follow <a class="reference external" href="https://www.patternfly.org/styles/terminology-and-wording/#terminology-and-wording-for-action-labels">these guidelines</a>.
As a rule of thumb, ‘Create’ and ‘Delete’ are the proper wording for most forms,
instead of ‘Add’ and ‘Remove’, unless some already created item is either added
or removed to/from a set of items (e.g.: ‘Add permission’ to a user vs. ‘Create
(new) permission’).</p>
<p>In order to enforce the use of this wording, a service <code class="docutils literal notranslate"><span class="pre">ActionLabelsI18n</span></code> has
been created, which provides translated labels for use in UI elements.</p>
</section>
<section id="frontend-branding">
<h3><a class="toc-backref" href="#id58" role="doc-backlink">Frontend branding</a><a class="headerlink" href="#frontend-branding" title="Permalink to this heading"></a></h3>
<p>Every vendor can customize the ‘Ceph dashboard’ to his needs. No matter if
logo, HTML-Template or TypeScript, every file inside the frontend folder can be
replaced.</p>
<p>To replace files, open <code class="docutils literal notranslate"><span class="pre">./frontend/angular.json</span></code> and scroll to the section
<code class="docutils literal notranslate"><span class="pre">fileReplacements</span></code> inside the production configuration. Here you can add the
files you wish to brand. We recommend to place the branded version of a file in
the same directory as the original one and to add a <code class="docutils literal notranslate"><span class="pre">.brand</span></code> to the file
name, right in front of the file extension. A <code class="docutils literal notranslate"><span class="pre">fileReplacement</span></code> could for
example look like this:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w">  </span><span class="s2">&quot;replace&quot;</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;src/app/core/auth/login/login.component.html&quot;</span><span class="p">,</span>
<span class="w">  </span><span class="s2">&quot;with&quot;</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;src/app/core/auth/login/login.component.brand.html&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>To serve or build the branded user interface run:</p>
<blockquote>
<div><p>$ npm run start -- --prod</p>
</div></blockquote>
<p>or</p>
<blockquote>
<div><p>$ npm run build -- --prod</p>
</div></blockquote>
<p>Unfortunately it’s currently not possible to use multiple configurations when
serving or building the UI at the same time. That means a configuration just
for the branding <code class="docutils literal notranslate"><span class="pre">fileReplacements</span></code> is not an option, because you want to use
the production configuration anyway
(<a class="reference external" href="https://github.com/angular/angular-cli/issues/10612">https://github.com/angular/angular-cli/issues/10612</a>).
Furthermore it’s also not possible to use glob expressions for
<code class="docutils literal notranslate"><span class="pre">fileReplacements</span></code>. As long as the feature hasn’t been implemented, you have
to add the file replacements manually to the angular.json file
(<a class="reference external" href="https://github.com/angular/angular-cli/issues/12354">https://github.com/angular/angular-cli/issues/12354</a>).</p>
<p>Nevertheless you should stick to the suggested naming scheme because it makes
it easier for you to use glob expressions once it’s supported in the future.</p>
<p>To change the variable defaults or add your own ones you can overwrite them in
<code class="docutils literal notranslate"><span class="pre">./frontend/src/styles/vendor/_variables.scss</span></code>.
Just reassign the variable you want to change, for example <code class="docutils literal notranslate"><span class="pre">$color-primary:</span> <span class="pre">teal;</span></code>
To overwrite or extend the default CSS, you can add your own styles in
<code class="docutils literal notranslate"><span class="pre">./frontend/src/styles/vendor/_style-overrides.scss</span></code>.</p>
</section>
<section id="ui-style-guide">
<h3><a class="toc-backref" href="#id59" role="doc-backlink">UI Style Guide</a><a class="headerlink" href="#ui-style-guide" title="Permalink to this heading"></a></h3>
<p>The style guide is created to document Ceph Dashboard standards and maintain
consistency across the project. Its an effort to make it easier for
contributors to process designing and deciding mockups and designs for
Dashboard.</p>
<p>The development environment for Ceph Dashboard has live reloading enabled so
any changes made in UI are reflected in open browser windows. Ceph Dashboard
uses Bootstrap as the main third-party CSS library.</p>
<p>Avoid duplication of code. Be consistent with the existing UI by reusing
existing SCSS declarations as much as possible.</p>
<p>Always check for existing code similar to what you want to write.
You should always try to keep the same look-and-feel as the existing code.</p>
<section id="colors">
<h4><a class="toc-backref" href="#id60" role="doc-backlink">Colors</a><a class="headerlink" href="#colors" title="Permalink to this heading"></a></h4>
<p>All the colors used in Ceph Dashboard UI are listed in
<cite>frontend/src/styles/defaults/_bootstrap-defaults.scss</cite>. If using new color
always define color variables in the <cite>_bootstrap-defaults.scss</cite> and
use the variable instead of hard coded color values so that changes to the
color are reflected in similar UI elements.</p>
<p>The main color for the Ceph Dashboard is <cite>$primary</cite>. The primary color is
used in navigation components and as the <cite>$border-color</cite> for input components of
form.</p>
<p>The secondary color is <cite>$secondary</cite> and is the background color for Ceph
Dashboard.</p>
</section>
<section id="buttons">
<h4><a class="toc-backref" href="#id61" role="doc-backlink">Buttons</a><a class="headerlink" href="#buttons" title="Permalink to this heading"></a></h4>
<p>Buttons are used for performing actions such as: “Submit”, “Edit, “Create” and
“Update”.</p>
<p><strong>Forms:</strong> When using to submit forms anywhere in the Dashboard, the main action
button should use the <cite>cd-submit-button</cite> component and the secondary button should
use <cite>cd-back-button</cite> component. The text on the action button should be same as the
form title and follow a title case. The text on the secondary button should be
<cite>Cancel</cite>. <cite>Perform action</cite> button should always be on right while <cite>Cancel</cite>
button should always be on left.</p>
<p><strong>Modals</strong>: The main action button should use the <cite>cd-submit-button</cite> component and
the secondary button should use <cite>cd-back-button</cite> component. The text on the action
button should follow a title case and correspond to the action to be performed.
The text on the secondary button should be <cite>Close</cite>.</p>
<p><strong>Disclosure Button:</strong> Disclosure buttons should be used to allow users to
display and hide additional content in the interface.</p>
<p><strong>Action Button</strong>: Use the action button to perform actions such as edit or update
a component. All action button should have an icon corresponding to the actions they
perform and button text should follow title case. The button color should be the
same as the form’s main button color.</p>
<p><strong>Drop Down Buttons:</strong> Use dropdown buttons to display predefined lists of
actions. All drop down buttons have icons corresponding to the action they
perform.</p>
</section>
<section id="links">
<h4><a class="toc-backref" href="#id62" role="doc-backlink">Links</a><a class="headerlink" href="#links" title="Permalink to this heading"></a></h4>
<p>Use text hyperlinks as navigation to guide users to a new page in the application
or to anchor users to a section within a page. The color of the hyperlinks
should be <cite>$primary</cite>.</p>
</section>
<section id="forms">
<h4><a class="toc-backref" href="#id63" role="doc-backlink">Forms</a><a class="headerlink" href="#forms" title="Permalink to this heading"></a></h4>
<p>Mark invalid form fields with red outline and show a meaningful error message.
Use red as font color for message and be as specific as possible.
<cite>This field is required.</cite> should be the exact error message for required fields.
Mark valid forms with a green outline and a green tick at the end of the form.
Sections should not have a bigger header than the parent.</p>
</section>
<section id="modals">
<h4><a class="toc-backref" href="#id64" role="doc-backlink">Modals</a><a class="headerlink" href="#modals" title="Permalink to this heading"></a></h4>
<p>Blur any interface elements in the background to bring the modal content into
focus. The heading of the modal should reflect the action it can perform and
should be clearly mentioned at the top of the modal. Use <cite>cd-back-button</cite>
component in the footer for closing the modal.</p>
</section>
<section id="icons">
<h4><a class="toc-backref" href="#id65" role="doc-backlink">Icons</a><a class="headerlink" href="#icons" title="Permalink to this heading"></a></h4>
<p>We use <a class="reference external" href="https://forkaweso.me/Fork-Awesome/">Fork Awesome</a> classes for icons.
We have a list of used icons in <cite>src/app/shared/enum/icons.enum.ts</cite>, these
should be referenced in the HTML, so its easier to change them later. When
icons are next to text, they should be center-aligned horizontally. If icons
are stacked, they should also be center-aligned vertically. Use small icons
with buttons. For notifications use large icons.</p>
</section>
<section id="navigation">
<h4><a class="toc-backref" href="#id66" role="doc-backlink">Navigation</a><a class="headerlink" href="#navigation" title="Permalink to this heading"></a></h4>
<p>For local navigation use tabs. For overall navigation use expandable vertical
navigation to collapse and expand items as needed.</p>
</section>
<section id="alerts-and-notifications">
<h4><a class="toc-backref" href="#id67" role="doc-backlink">Alerts and notifications</a><a class="headerlink" href="#alerts-and-notifications" title="Permalink to this heading"></a></h4>
<p>Default notification should have <cite>text-info</cite> color. Success notification should
have <cite>text-success</cite> color. Failure notification should have <cite>text-danger</cite> color.</p>
</section>
</section>
<section id="error-handling">
<h3><a class="toc-backref" href="#id68" role="doc-backlink">Error Handling</a><a class="headerlink" href="#error-handling" title="Permalink to this heading"></a></h3>
<p>For handling front-end errors, there is a generic Error Component which can be
found in <code class="docutils literal notranslate"><span class="pre">./src/pybind/mgr/dashboard/frontend/src/app/core/error</span></code>. For
reporting a new error, you can simply extend the <code class="docutils literal notranslate"><span class="pre">DashboardError</span></code> class
in <code class="docutils literal notranslate"><span class="pre">error.ts</span></code> file and add specific header and message for the new error. Some
generic error classes are already in place such as <code class="docutils literal notranslate"><span class="pre">DashboardNotFoundError</span></code>
and <code class="docutils literal notranslate"><span class="pre">DashboardForbiddenError</span></code> which can be called and reused in different
scenarios.</p>
<p>For example - <code class="docutils literal notranslate"><span class="pre">throw</span> <span class="pre">new</span> <span class="pre">DashboardNotFoundError()</span></code>.</p>
</section>
</section>
<section id="internationalization-i18n">
<h2><a class="toc-backref" href="#id69" role="doc-backlink">Internationalization (i18n)</a><a class="headerlink" href="#internationalization-i18n" title="Permalink to this heading"></a></h2>
<section id="how-to-extract-messages-from-source-code">
<h3><a class="toc-backref" href="#id70" role="doc-backlink">How to extract messages from source code?</a><a class="headerlink" href="#how-to-extract-messages-from-source-code" title="Permalink to this heading"></a></h3>
<p>To extract the I18N messages from the templates and the TypeScript files just
run the following command in <code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ npm run i18n:extract
</pre></div>
</div>
<p>This will extract all marked messages from the HTML templates first and then
add all marked strings from the TypeScript files to the translation template.
Since the extraction from TypeScript files is still not supported by Angular
itself, we are using the
<a class="reference external" href="https://github.com/ngx-translate/i18n-polyfill">ngx-translator</a> extractor to
parse the TypeScript files.</p>
<p>When the command ran successfully, it should have created or updated the file
<code class="docutils literal notranslate"><span class="pre">src/locale/messages.xlf</span></code>.</p>
<p>The file isn’t tracked by git, you can just use it to start with the
translation offline or add/update the resource files on transifex.</p>
</section>
<section id="supported-languages">
<h3><a class="toc-backref" href="#id71" role="doc-backlink">Supported languages</a><a class="headerlink" href="#supported-languages" title="Permalink to this heading"></a></h3>
<p>All our supported languages should be registered in both exports in
<code class="docutils literal notranslate"><span class="pre">supported-languages.enum.ts</span></code> and have a corresponding test in
<code class="docutils literal notranslate"><span class="pre">language-selector.component.spec.ts</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">SupportedLanguages</span></code> enum will provide the list for the default language selection.</p>
</section>
<section id="translating-process">
<h3><a class="toc-backref" href="#id72" role="doc-backlink">Translating process</a><a class="headerlink" href="#translating-process" title="Permalink to this heading"></a></h3>
<p>To facilitate the translation process of the dashboard we are using a web tool
called <a class="reference external" href="https://www.transifex.com/">transifex</a>.</p>
<p>If you wish to help translating to any language just go to our <a class="reference external" href="https://www.transifex.com/ceph/ceph-dashboard/">transifex
project page</a>, join the
project and you can start translating immediately.</p>
<p>All translations will then be reviewed and later pushed upstream.</p>
</section>
<section id="updating-translated-messages">
<h3><a class="toc-backref" href="#id73" role="doc-backlink">Updating translated messages</a><a class="headerlink" href="#updating-translated-messages" title="Permalink to this heading"></a></h3>
<p>Any time there are new messages translated and reviewed in a specific language
we should update the translation file upstream.</p>
<p>To do that, check the settings in the i18n config file
<code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend/i18n.config.json</span></code>:: and make sure that the
organization is <em>ceph</em>, the project is <em>ceph-dashboard</em> and the resource is
the one you want to pull from and push to e.g. <em>Master:master</em>. To find a list
of available resources visit <a class="reference external" href="https://www.transifex.com/ceph/ceph-dashboard/content/">https://www.transifex.com/ceph/ceph-dashboard/content/</a>.</p>
<p>After you checked the config go to the directory <code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend</span></code> and run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ npm run i18n
</pre></div>
</div>
<p>This command will extract all marked messages from the HTML templates and
TypeScript files. Once the source file has been created it will push it to
transifex and pull the latest translations. It will also fill all the
untranslated strings with the source string.
The tool will ask you for an api token, unless you added it by running:</p>
<blockquote>
<div><p>$ npm run i18n:token</p>
</div></blockquote>
<p>To create a transifex api token visit <a class="reference external" href="https://www.transifex.com/user/settings/api/">https://www.transifex.com/user/settings/api/</a>.</p>
<p>After the command ran successfully, build the UI and check if everything is
working as expected. You also might want to run the frontend tests.</p>
</section>
<section id="add-a-new-release-resource-to-transifex">
<h3><a class="toc-backref" href="#id74" role="doc-backlink">Add a new release resource to transifex</a><a class="headerlink" href="#add-a-new-release-resource-to-transifex" title="Permalink to this heading"></a></h3>
<p>In order to organize the translations, we create a
<a class="reference external" href="https://www.transifex.com/ceph/ceph-dashboard/content/">transifex resource</a>
for every Ceph release. This means, once a new version has been released, the
<code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/frontend/i18n.config.json</span></code> needs to be updated on
the release branch.</p>
<p>Please replace:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;resource&quot;</span><span class="p">:</span> <span class="s2">&quot;Master:master&quot;</span>
</pre></div>
</div>
<p>by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;resource&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;Release-name&gt;:&lt;release-name&gt;&quot;</span>
</pre></div>
</div>
<p>E.g. the resource definition for the pacific release:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;resource&quot;</span><span class="p">:</span> <span class="s2">&quot;Pacific:pacific&quot;</span>
</pre></div>
</div>
<dl class="simple">
<dt>Note:</dt><dd><p>The first part of the resource definition (before the colon) needs to be
written with a capital letter.</p>
</dd>
</dl>
</section>
<section id="suggestions">
<h3><a class="toc-backref" href="#id75" role="doc-backlink">Suggestions</a><a class="headerlink" href="#suggestions" title="Permalink to this heading"></a></h3>
<p>Strings need to start and end in the same line as the element:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cm">&lt;!-- avoid --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>
  Foo
<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>

<span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>Foo<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>


<span class="cm">&lt;!-- avoid --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>
  Foo bar baz.
  Foo bar baz.
<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>

<span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>Foo bar baz.
  Foo bar baz.<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Isolated interpolations should not be translated:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cm">&lt;!-- avoid --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>{{ foo }}<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>

<span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span><span class="p">&gt;</span>{{ foo }}<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Interpolations used in a sentence should be kept in the translation:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>There are {{ x }} OSDs.<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Remove elements that are outside the context of the translation:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cm">&lt;!-- avoid --&gt;</span>
<span class="p">&lt;</span><span class="nt">label</span> <span class="na">i18n</span><span class="p">&gt;</span>
  Profile
  <span class="p">&lt;</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;required&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">label</span><span class="p">&gt;</span>

<span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">label</span><span class="p">&gt;</span>
  <span class="p">&lt;</span><span class="nt">ng-container</span> <span class="na">i18n</span><span class="p">&gt;</span>Profile<span class="p">&lt;</span><span class="nt">ng-container</span><span class="p">&gt;</span>
  <span class="p">&lt;</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;required&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">label</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Keep elements that affect the sentence:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cm">&lt;!-- recommended --&gt;</span>
<span class="p">&lt;</span><span class="nt">span</span> <span class="na">i18n</span><span class="p">&gt;</span>Profile <span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>foo<span class="p">&lt;/</span><span class="nt">b</span><span class="p">&gt;</span> will be removed.<span class="p">&lt;/</span><span class="nt">span</span><span class="p">&gt;</span>
</pre></div>
</div>
</section>
</section>
<section id="accessibility">
<span id="id1"></span><h2><a class="toc-backref" href="#id76" role="doc-backlink">Accessibility</a><a class="headerlink" href="#accessibility" title="Permalink to this heading"></a></h2>
<p>Many parts of the Ceph Dashboard are modeled on <a class="reference external" href="https://www.w3.org/TR/WCAG21/">Web Content Accessibility Guidelines (WCAG) 2.1</a>  level A accessibility conformance guidelines.
By implementing accessibility best practices, you are improving the usability of the Ceph Dashboard for blind and visually impaired users.</p>
<section id="summary">
<h3><a class="toc-backref" href="#id77" role="doc-backlink">Summary</a><a class="headerlink" href="#summary" title="Permalink to this heading"></a></h3>
<p>A few things you should check before introducing a new code change include:</p>
<ol class="arabic simple">
<li><p>Add <a class="reference external" href="https://www.w3.org/TR/wai-aria/">ARIA labels and descriptions</a> to actionable HTML elements.</p></li>
<li><p>Don’t forget to tag ARIA labels/descriptions or any user-readable text for translation (i18n-title, i18n-aria-label…).</p></li>
<li><p>Add <a class="reference external" href="https://www.w3.org/TR/wai-aria/#usage_intro">ARIA roles</a> to tag HTML elements that behave different from their intended behaviour (&lt;a&gt; tags behaving as &lt;buttons&gt;) or that provide extended behaviours (roles).</p></li>
<li><p>Avoid poor <a class="reference external" href="https://www.w3.org/TR/WCAG21/#contrast-minimum">color contrast choices</a> (foreground-background) when styling a component. Here are some <a class="reference internal" href="#color-contrast-checkers"><span class="std std-ref">tools</span></a> you can use.</p></li>
<li><p>When testing menus or dropdowns, be sure to scan them with an <a class="reference internal" href="#accessibility-checkers"><span class="std std-ref">accessibility checker</span></a> in both opened and closed states. Sometimes issues are hidden when menus are closed.</p></li>
</ol>
</section>
<section id="accessibility-checkers">
<span id="id2"></span><h3><a class="toc-backref" href="#id78" role="doc-backlink">Accessibility checkers</a><a class="headerlink" href="#accessibility-checkers" title="Permalink to this heading"></a></h3>
<p>During development, you can test the accessibility compliance of your features using one of the tools below:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://accessibilityinsights.io/downloads/">Accessibility insights plugin</a></p></li>
<li><p><a class="reference external" href="https://www.siteimprove.com/integrations/browser-extensions/">Site Improve plugin</a></p></li>
<li><p><a class="reference external" href="https://www.deque.com/axe/devtools/">Axe devtools</a></p></li>
</ul>
<p>Testing with two or more of these tools can greatly improve the detection of accessibility violations.</p>
</section>
<section id="color-contrast-checkers">
<span id="id3"></span><h3><a class="toc-backref" href="#id79" role="doc-backlink">Color contrast checkers</a><a class="headerlink" href="#color-contrast-checkers" title="Permalink to this heading"></a></h3>
<p>When adding new colors, making sure they are accessible is also important. Here are some tools which can help with color contrast testing:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://accessibleweb.com/color-contrast-checker/">Accessible web color-contrast checker</a></p></li>
<li><p><a class="reference external" href="https://colorsafe.co/">Colorsafe generator</a></p></li>
</ul>
</section>
<section id="accessibility-linters">
<h3><a class="toc-backref" href="#id80" role="doc-backlink">Accessibility linters</a><a class="headerlink" href="#accessibility-linters" title="Permalink to this heading"></a></h3>
<p>If you use VSCode, you may install the <a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=deque-systems.vscode-axe-linter">axe accessibility linter</a>,
which can help you catch and fix potential issues during development.</p>
</section>
<section id="accessibility-testing">
<h3><a class="toc-backref" href="#id81" role="doc-backlink">Accessibility testing</a><a class="headerlink" href="#accessibility-testing" title="Permalink to this heading"></a></h3>
<p>Our e2e testing suite, which is based on Cypress, supports the addition of accessibility tests using <a class="reference external" href="https://github.com/dequelabs/axe-core">axe-core</a>
and <a class="reference external" href="https://github.com/component-driven/cypress-axe">cypress-axe</a>. A custom Cypress command, <cite>cy.checkAccessibility</cite>, can also be used directly.
This is a great way to prevent accessibility regressions on high impact components.</p>
<p>Tests can be found under the <a class="reference external" href="./src/pybind/mgr/dashboard/frontend/cypress/integration/a11y">a11y folder</a> in the dashboard. Here is an example:</p>
<div class="highlight-TypeScript notranslate"><div class="highlight"><pre><span></span><span class="nx">describe</span><span class="p">(</span><span class="s1">&#39;Navigation accessibility&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">retries</span><span class="o">:</span><span class="w"> </span><span class="kt">0</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="kd">const</span><span class="w"> </span><span class="nx">shared</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="nx">NavigationPageHelper</span><span class="p">();</span>

<span class="w">  </span><span class="nx">beforeEach</span><span class="p">(()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">login</span><span class="p">();</span>
<span class="w">    </span><span class="nx">shared</span><span class="p">.</span><span class="nx">navigateTo</span><span class="p">();</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="nx">it</span><span class="p">(</span><span class="s1">&#39;top-nav should have no accessibility violations&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">injectAxe</span><span class="p">();</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">checkAccessibility</span><span class="p">(</span><span class="s1">&#39;.cd-navbar-top&#39;</span><span class="p">);</span>
<span class="w">  </span><span class="p">});</span>

<span class="w">  </span><span class="nx">it</span><span class="p">(</span><span class="s1">&#39;sidebar should have no accessibility violations&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">injectAxe</span><span class="p">();</span>
<span class="w">    </span><span class="nx">cy</span><span class="p">.</span><span class="nx">checkAccessibility</span><span class="p">(</span><span class="s1">&#39;nav[id=sidebar]&#39;</span><span class="p">);</span>
<span class="w">  </span><span class="p">});</span>

<span class="p">});</span>
</pre></div>
</div>
</section>
<section id="additional-guidelines">
<h3><a class="toc-backref" href="#id82" role="doc-backlink">Additional guidelines</a><a class="headerlink" href="#additional-guidelines" title="Permalink to this heading"></a></h3>
<p>If you’re unsure about which UI pattern to follow in order to implement an accessibility fix, <a class="reference external" href="https://www.patternfly.org/v4/accessibility/accessibility-fundamentals">patternfly</a> guidelines can be used.</p>
</section>
</section>
<section id="backend-development">
<h2><a class="toc-backref" href="#id83" role="doc-backlink">Backend Development</a><a class="headerlink" href="#backend-development" title="Permalink to this heading"></a></h2>
<p>The Python backend code of this module requires a number of Python modules to be
installed. They are listed in file <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code>. Using <a class="reference external" href="https://pypi.python.org/pypi/pip">pip</a> you may install all required dependencies
by issuing <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements.txt</span></code> in directory
<code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard</span></code>.</p>
<p>If you’re using the <a class="reference external" href="https://github.com/ricardoasmarques/ceph-dev-docker/">ceph-dev-docker development environment</a>, simply run
<code class="docutils literal notranslate"><span class="pre">./install_deps.sh</span></code> from the toplevel directory to install them.</p>
<section id="unit-testing">
<h3><a class="toc-backref" href="#id84" role="doc-backlink">Unit Testing</a><a class="headerlink" href="#unit-testing" title="Permalink to this heading"></a></h3>
<p>In dashboard we have two different kinds of backend tests:</p>
<ol class="arabic simple">
<li><p>Unit tests based on <code class="docutils literal notranslate"><span class="pre">tox</span></code></p></li>
<li><p>API tests based on Teuthology.</p></li>
</ol>
</section>
<section id="unit-tests-based-on-tox">
<h3><a class="toc-backref" href="#id85" role="doc-backlink">Unit tests based on tox</a><a class="headerlink" href="#unit-tests-based-on-tox" title="Permalink to this heading"></a></h3>
<p>We included a <code class="docutils literal notranslate"><span class="pre">tox</span></code> configuration file that will run the unit tests under
Python 3, as well as linting tools to guarantee the uniformity of code.</p>
<p>You need to install <code class="docutils literal notranslate"><span class="pre">tox</span></code> and <code class="docutils literal notranslate"><span class="pre">coverage</span></code> before running it. To install the
packages in your system, either install it via your operating system’s package
management tools, e.g. by running <code class="docutils literal notranslate"><span class="pre">dnf</span> <span class="pre">install</span> <span class="pre">python-tox</span> <span class="pre">python-coverage</span></code> on
Fedora Linux.</p>
<p>Alternatively, you can use Python’s native package installation method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install tox
$ pip install coverage
</pre></div>
</div>
<p>To run the tests, run <code class="docutils literal notranslate"><span class="pre">src/script/run_tox.sh</span></code> in the dashboard directory (where
<code class="docutils literal notranslate"><span class="pre">tox.ini</span></code> is located):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>## Run Python 3 tests+lint commands:
$ ../../../script/run_tox.sh --tox-env py3,lint,check

## Run Python 3 arbitrary command (e.g. 1 single test):
$ ../../../script/run_tox.sh --tox-env py3 &quot;&quot; tests/test_rgw_client.py::RgwClientTest::test_ssl_verify
</pre></div>
</div>
<p>You can also run tox instead of <code class="docutils literal notranslate"><span class="pre">run_tox.sh</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>## Run Python 3 tests command:
$ tox -e py3

## Run Python 3 arbitrary command (e.g. 1 single test):
$ tox -e py3 tests/test_rgw_client.py::RgwClientTest::test_ssl_verify
</pre></div>
</div>
<p>Python files can be automatically fixed and formatted according to PEP8
standards by using <code class="docutils literal notranslate"><span class="pre">run_tox.sh</span> <span class="pre">--tox-env</span> <span class="pre">fix</span></code> or <code class="docutils literal notranslate"><span class="pre">tox</span> <span class="pre">-e</span> <span class="pre">fix</span></code>.</p>
<p>We also collect coverage information from the backend code when you run tests. You can check the
coverage information provided by the tox output, or by running the following
command after tox has finished successfully:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ coverage html
</pre></div>
</div>
<p>This command will create a directory <code class="docutils literal notranslate"><span class="pre">htmlcov</span></code> with an HTML representation of
the code coverage of the backend.</p>
</section>
<section id="api-tests-based-on-teuthology">
<h3><a class="toc-backref" href="#id86" role="doc-backlink">API tests based on Teuthology</a><a class="headerlink" href="#api-tests-based-on-teuthology" title="Permalink to this heading"></a></h3>
<dl>
<dt>How to run existing API tests:</dt><dd><p>To run the API tests against a real Ceph cluster, we leverage the Teuthology
framework. This has the advantage of catching bugs originated from changes in
the internal Ceph code.</p>
<p>Our <code class="docutils literal notranslate"><span class="pre">run-backend-api-tests.sh</span></code> script will start a <code class="docutils literal notranslate"><span class="pre">vstart</span></code> Ceph cluster
before running the Teuthology tests, and then it stops the cluster after the
tests are run. Of course this implies that you have built/compiled Ceph
previously.</p>
<p>Start all dashboard tests by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./run-backend-api-tests.sh
</pre></div>
</div>
<p>Or, start one or multiple specific tests by specifying the test name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./run-backend-api-tests.sh tasks.mgr.dashboard.test_pool.PoolTest
</pre></div>
</div>
<p>Or, <code class="docutils literal notranslate"><span class="pre">source</span></code> the script and run the tests manually:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ source run-backend-api-tests.sh
$ run_teuthology_tests [tests]...
$ cleanup_teuthology
</pre></div>
</div>
</dd>
<dt>How to write your own tests:</dt><dd><p>There are two possible ways to write your own API tests:</p>
<p>The first is by extending one of the existing test classes in the
<code class="docutils literal notranslate"><span class="pre">qa/tasks/mgr/dashboard</span></code> directory.</p>
<p>The second way is by adding your own API test module if you’re creating a new
controller for example. To do so you’ll just need to add the file containing
your new test class to the <code class="docutils literal notranslate"><span class="pre">qa/tasks/mgr/dashboard</span></code> directory and implement
all your tests here.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Don’t forget to add the path of the newly created module to
<code class="docutils literal notranslate"><span class="pre">modules</span></code> section in <code class="docutils literal notranslate"><span class="pre">qa/suites/rados/mgr/tasks/dashboard.yaml</span></code>.</p>
</div>
<p>Short example: Let’s assume you created a new controller called
<code class="docutils literal notranslate"><span class="pre">my_new_controller.py</span></code> and the related test module
<code class="docutils literal notranslate"><span class="pre">test_my_new_controller.py</span></code>. You’ll need to add
<code class="docutils literal notranslate"><span class="pre">tasks.mgr.dashboard.test_my_new_controller</span></code> to the <code class="docutils literal notranslate"><span class="pre">modules</span></code> section in
the <code class="docutils literal notranslate"><span class="pre">dashboard.yaml</span></code> file.</p>
<p>Also, if you’re removing test modules please keep in mind to remove the
related section. Otherwise the Teuthology test run will fail.</p>
<p>Please run your API tests on your dev environment (as explained above)
before submitting a pull request. Also make sure that a full QA run in
Teuthology/sepia lab (based on your changes) has completed successfully
before it gets merged. You don’t need to schedule the QA run yourself, just
add the ‘needs-qa’ label to your pull request as soon as you think it’s ready
for merging (e.g. make check was successful, the pull request is approved and
all comments have been addressed). One of the developers who has access to
Teuthology/the sepia lab will take care of it and report the result back to
you.</p>
</dd>
</dl>
</section>
<section id="how-to-add-a-new-controller">
<h3><a class="toc-backref" href="#id87" role="doc-backlink">How to add a new controller?</a><a class="headerlink" href="#how-to-add-a-new-controller" title="Permalink to this heading"></a></h3>
<p>A controller is a Python class that extends from the <code class="docutils literal notranslate"><span class="pre">BaseController</span></code> class
and is decorated with either the <code class="docutils literal notranslate"><span class="pre">&#64;Controller</span></code>, <code class="docutils literal notranslate"><span class="pre">&#64;ApiController</span></code> or
<code class="docutils literal notranslate"><span class="pre">&#64;UiApiController</span></code> decorators. The Python class must be stored inside a Python
file located under the <code class="docutils literal notranslate"><span class="pre">controllers</span></code> directory. The Dashboard module will
automatically load your new controller upon start.</p>
<p><code class="docutils literal notranslate"><span class="pre">&#64;ApiController</span></code> and <code class="docutils literal notranslate"><span class="pre">&#64;UiApiController</span></code> are both specializations of the
<code class="docutils literal notranslate"><span class="pre">&#64;Controller</span></code> decorator.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;ApiController</span></code> should be used for controllers that provide an API-like
REST interface and the <code class="docutils literal notranslate"><span class="pre">&#64;UiApiController</span></code> should be used for endpoints consumed
by the UI but that are not part of the ‘public’ API. For any other kinds of
controllers the <code class="docutils literal notranslate"><span class="pre">&#64;Controller</span></code> decorator should be used.</p>
<p>A controller has a URL prefix path associated that is specified in the
controller decorator, and all endpoints exposed by the controller will share
the same URL prefix path.</p>
<p>A controller’s endpoint is exposed by implementing a method on the controller
class decorated with the <code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code> decorator.</p>
<p>For example create a file <code class="docutils literal notranslate"><span class="pre">ping.py</span></code> under <code class="docutils literal notranslate"><span class="pre">controllers</span></code> directory with the
following code:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">Controller</span><span class="p">,</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">UiApiController</span><span class="p">,</span> <span class="n">BaseController</span><span class="p">,</span> <span class="n">Endpoint</span>

<span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
  <span class="nd">@Endpoint</span><span class="p">()</span>
  <span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;msg&#39;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>

<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">ApiPing</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
  <span class="nd">@Endpoint</span><span class="p">()</span>
  <span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;msg&#39;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>

<span class="nd">@UiApiController</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">UiApiPing</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
  <span class="nd">@Endpoint</span><span class="p">()</span>
  <span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;msg&#39;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">hello</span></code> endpoint of the <code class="docutils literal notranslate"><span class="pre">Ping</span></code> controller can be reached by the
following URL: <a class="reference external" href="https://mgr_hostname:8443/ping/hello">https://mgr_hostname:8443/ping/hello</a> using HTTP GET requests.
As you can see the controller URL path <code class="docutils literal notranslate"><span class="pre">/ping</span></code> is concatenated to the
method name <code class="docutils literal notranslate"><span class="pre">hello</span></code> to generate the endpoint’s URL.</p>
<p>In the case of the <code class="docutils literal notranslate"><span class="pre">ApiPing</span></code> controller, the <code class="docutils literal notranslate"><span class="pre">hello</span></code> endpoint can be
reached by the following URL: <a class="reference external" href="https://mgr_hostname:8443/api/ping/hello">https://mgr_hostname:8443/api/ping/hello</a> using a
HTTP GET request.
The API controller URL path <code class="docutils literal notranslate"><span class="pre">/ping</span></code> is prefixed by the <code class="docutils literal notranslate"><span class="pre">/api</span></code> path and then
concatenated to the method name <code class="docutils literal notranslate"><span class="pre">hello</span></code> to generate the endpoint’s URL.
Internally, the <code class="docutils literal notranslate"><span class="pre">&#64;ApiController</span></code> is actually calling the <code class="docutils literal notranslate"><span class="pre">&#64;Controller</span></code>
decorator by passing an additional decorator parameter called <code class="docutils literal notranslate"><span class="pre">base_url</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span> <span class="o">&lt;=&gt;</span> <span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="s2">&quot;/api&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">UiApiPing</span></code> works in a similar way than the <code class="docutils literal notranslate"><span class="pre">ApiPing</span></code>, but the URL will be
prefixed by <code class="docutils literal notranslate"><span class="pre">/ui-api</span></code>: <a class="reference external" href="https://mgr_hostname:8443/ui-api/ping/hello">https://mgr_hostname:8443/ui-api/ping/hello</a>. <code class="docutils literal notranslate"><span class="pre">UiApiPing</span></code> is
also a <code class="docutils literal notranslate"><span class="pre">&#64;Controller</span></code> extension:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@UiApiController</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span> <span class="o">&lt;=&gt;</span> <span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="s2">&quot;/ui-api&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code> decorator also supports many parameters to customize the
endpoint:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">method=&quot;GET&quot;</span></code>: the HTTP method allowed to access this endpoint.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">path=&quot;/&lt;method_name&gt;&quot;</span></code>: the URL path of the endpoint, excluding the
controller URL path prefix.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">path_params=[]</span></code>: list of method parameter names that correspond to URL
path parameters. Can only be used when <code class="docutils literal notranslate"><span class="pre">method</span> <span class="pre">in</span> <span class="pre">['POST',</span> <span class="pre">'PUT']</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">query_params=[]</span></code>: list of method parameter names that correspond to URL
query parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">json_response=True</span></code>: indicates if the endpoint response should be
serialized in JSON format.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">proxy=False</span></code>: indicates if the endpoint should be used as a proxy.</p></li>
</ul>
<p>An endpoint method may have parameters declared. Depending on the HTTP method
defined for the endpoint the method parameters might be considered either
path parameters, query parameters, or body parameters.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">GET</span></code> and <code class="docutils literal notranslate"><span class="pre">DELETE</span></code> methods, the method’s non-optional parameters are
considered path parameters by default. Optional parameters are considered
query parameters. By specifying the <code class="docutils literal notranslate"><span class="pre">query_parameters</span></code> in the endpoint
decorator it is possible to make a non-optional parameter to be a query
parameter.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">POST</span></code> and <code class="docutils literal notranslate"><span class="pre">PUT</span></code> methods, all method parameters are considered
body parameters by default. To override this default, one can use the
<code class="docutils literal notranslate"><span class="pre">path_params</span></code> and <code class="docutils literal notranslate"><span class="pre">query_params</span></code> to specify which method parameters are
path and query parameters respectively.
Body parameters are decoded from the request body, either from a form format, or
from a dictionary in JSON format.</p>
<p>Let’s use an example to better understand the possible ways to customize an
endpoint:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">Controller</span><span class="p">,</span> <span class="n">BaseController</span><span class="p">,</span> <span class="n">Endpoint</span>

<span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/ping&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>

  <span class="c1"># URL: /ping/{key}?opt1=...&amp;opt2=...</span>
  <span class="nd">@Endpoint</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s2">&quot;/&quot;</span><span class="p">,</span> <span class="n">query_params</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;opt1&#39;</span><span class="p">])</span>
  <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">opt1</span><span class="p">,</span> <span class="n">opt2</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;...&quot;&quot;&quot;</span>

  <span class="c1"># URL: /ping/{key}?opt1=...&amp;opt2=...</span>
  <span class="nd">@Endpoint</span><span class="p">(</span><span class="n">query_params</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;opt1&#39;</span><span class="p">])</span>
  <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">opt1</span><span class="p">,</span> <span class="n">opt2</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;...&quot;&quot;&quot;</span>

  <span class="c1"># URL: /ping/post/{key1}/{key2}</span>
  <span class="nd">@Endpoint</span><span class="p">(</span><span class="s1">&#39;POST&#39;</span><span class="p">,</span> <span class="n">path_params</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;key1&#39;</span><span class="p">,</span> <span class="s1">&#39;key2&#39;</span><span class="p">])</span>
  <span class="k">def</span> <span class="nf">post</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key1</span><span class="p">,</span> <span class="n">key2</span><span class="p">,</span> <span class="n">data1</span><span class="p">,</span> <span class="n">data2</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;...&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>In the above example we see how the <code class="docutils literal notranslate"><span class="pre">path</span></code> option can be used to override the
generated endpoint URL in order to not use the method’s name in the URL. In the
<code class="docutils literal notranslate"><span class="pre">index</span></code> method we set the <code class="docutils literal notranslate"><span class="pre">path</span></code> to <code class="docutils literal notranslate"><span class="pre">&quot;/&quot;</span></code> to generate an endpoint that is
accessible by the root URL of the controller.</p>
<p>An alternative approach to generate an endpoint that is accessible through just
the controller’s path URL is by using the <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method, as we show in
the above example.</p>
<p>From the third method you can see that the path parameters are collected from
the URL by parsing the list of values separated by slashes <code class="docutils literal notranslate"><span class="pre">/</span></code> that come
after the URL path <code class="docutils literal notranslate"><span class="pre">/ping</span></code> for <code class="docutils literal notranslate"><span class="pre">index</span></code> method case, and <code class="docutils literal notranslate"><span class="pre">/ping/post</span></code> for
the <code class="docutils literal notranslate"><span class="pre">post</span></code> method case.</p>
<p>Defining path parameters in endpoints’s URLs using python methods’s parameters
is very easy but it is still a bit strict with respect to the position of these
parameters in the URL structure.
Sometimes we may want to explicitly define a URL scheme that
contains path parameters mixed with static parts of the URL.
Our controller infrastructure also supports the declaration of URL paths with
explicit path parameters at both the controller level and method level.</p>
<p>Consider the following example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">Controller</span><span class="p">,</span> <span class="n">BaseController</span><span class="p">,</span> <span class="n">Endpoint</span>

<span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/ping/</span><span class="si">{node}</span><span class="s1">/stats&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>

  <span class="c1"># URL: /ping/{node}/stats/{date}/latency?unit=...</span>
  <span class="nd">@Endpoint</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s2">&quot;/</span><span class="si">{date}</span><span class="s2">/latency&quot;</span><span class="p">)</span>
  <span class="k">def</span> <span class="nf">latency</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">node</span><span class="p">,</span> <span class="n">date</span><span class="p">,</span> <span class="n">unit</span><span class="o">=</span><span class="s2">&quot;ms&quot;</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot; ...&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>In this example we explicitly declare a path parameter <code class="docutils literal notranslate"><span class="pre">{node}</span></code> in the
controller URL path, and a path parameter <code class="docutils literal notranslate"><span class="pre">{date}</span></code> in the <code class="docutils literal notranslate"><span class="pre">latency</span></code>
method. The endpoint for the <code class="docutils literal notranslate"><span class="pre">latency</span></code> method is then accessible through
the URL: <a class="reference external" href="https://mgr_hostname:8443/ping">https://mgr_hostname:8443/ping</a>/{node}/stats/{date}/latency .</p>
<p>For a full set of examples on how to use the <code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code>
decorator please check the unit test file: <code class="docutils literal notranslate"><span class="pre">tests/test_controllers.py</span></code>.
There you will find many examples of how to customize endpoint methods.</p>
</section>
<section id="implementing-proxy-controller">
<h3><a class="toc-backref" href="#id88" role="doc-backlink">Implementing Proxy Controller</a><a class="headerlink" href="#implementing-proxy-controller" title="Permalink to this heading"></a></h3>
<p>Sometimes you might need to relay some requests from the Dashboard frontend
directly to an external service.
For that purpose we provide a decorator called <code class="docutils literal notranslate"><span class="pre">&#64;Proxy</span></code>.
(As a concrete example, check the <code class="docutils literal notranslate"><span class="pre">controllers/rgw.py</span></code> file where we
implemented an RGW Admin Ops proxy.)</p>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;Proxy</span></code> decorator is a wrapper of the <code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code> decorator that
already customizes the endpoint for working as a proxy.
A proxy endpoint works by capturing the URL path that follows the controller
URL prefix path, and does not do any decoding of the request body.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">Controller</span><span class="p">,</span> <span class="n">BaseController</span><span class="p">,</span> <span class="n">Proxy</span>

<span class="nd">@Controller</span><span class="p">(</span><span class="s1">&#39;/foo/proxy&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">FooServiceProxy</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>

  <span class="nd">@Proxy</span><span class="p">()</span>
  <span class="k">def</span> <span class="nf">proxy</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="o">**</span><span class="n">params</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    if requested URL is &quot;/foo/proxy/access/service?opt=1&quot;</span>
<span class="sd">    then path is &quot;access/service&quot; and params is {&#39;opt&#39;: &#39;1&#39;}</span>
<span class="sd">    &quot;&quot;&quot;</span>
</pre></div>
</div>
</section>
<section id="how-does-the-restcontroller-work">
<h3><a class="toc-backref" href="#id89" role="doc-backlink">How does the RESTController work?</a><a class="headerlink" href="#how-does-the-restcontroller-work" title="Permalink to this heading"></a></h3>
<p>We also provide a simple mechanism to create REST based controllers using the
<code class="docutils literal notranslate"><span class="pre">RESTController</span></code> class. Any class which inherits from <code class="docutils literal notranslate"><span class="pre">RESTController</span></code> will,
by default, return JSON.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">RESTController</span></code> is basically an additional abstraction layer which eases
and unifies the work with collections. A collection is just an array of objects
with a specific type. <code class="docutils literal notranslate"><span class="pre">RESTController</span></code> enables some default mappings of
request types and given parameters to specific method names. This may sound
complicated at first, but it’s fairly easy. Lets have look at the following
example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;ping&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
  <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;msg&quot;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>

  <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
    <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">objects</span><span class="p">[</span><span class="nb">id</span><span class="p">]</span>
</pre></div>
</div>
<p>In this case, the <code class="docutils literal notranslate"><span class="pre">list</span></code> method is automatically used for all requests to
<code class="docutils literal notranslate"><span class="pre">api/ping</span></code> where no additional argument is given and where the request type
is <code class="docutils literal notranslate"><span class="pre">GET</span></code>. If the request is given an additional argument, the ID in our
case, it won’t map to <code class="docutils literal notranslate"><span class="pre">list</span></code> anymore but to <code class="docutils literal notranslate"><span class="pre">get</span></code> and return the element
with the given ID (assuming that <code class="docutils literal notranslate"><span class="pre">self.objects</span></code> has been filled before). The
same applies to other request types:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Request type</p></th>
<th class="head"><p>Arguments</p></th>
<th class="head"><p>Method</p></th>
<th class="head"><p>Status Code</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>GET</p></td>
<td><p>No</p></td>
<td><p>list</p></td>
<td><p>200</p></td>
</tr>
<tr class="row-odd"><td><p>PUT</p></td>
<td><p>No</p></td>
<td><p>bulk_set</p></td>
<td><p>200</p></td>
</tr>
<tr class="row-even"><td><p>POST</p></td>
<td><p>No</p></td>
<td><p>create</p></td>
<td><p>201</p></td>
</tr>
<tr class="row-odd"><td><p>DELETE</p></td>
<td><p>No</p></td>
<td><p>bulk_delete</p></td>
<td><p>204</p></td>
</tr>
<tr class="row-even"><td><p>GET</p></td>
<td><p>Yes</p></td>
<td><p>get</p></td>
<td><p>200</p></td>
</tr>
<tr class="row-odd"><td><p>PUT</p></td>
<td><p>Yes</p></td>
<td><p>set</p></td>
<td><p>200</p></td>
</tr>
<tr class="row-even"><td><p>DELETE</p></td>
<td><p>Yes</p></td>
<td><p>delete</p></td>
<td><p>204</p></td>
</tr>
</tbody>
</table>
<p>To use a custom endpoint for the above listed methods, you can
use <code class="docutils literal notranslate"><span class="pre">&#64;RESTController.MethodMap</span></code></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

  <span class="nd">@RESTController</span><span class="o">.</span><span class="n">MethodMap</span><span class="p">(</span><span class="n">version</span><span class="o">=</span><span class="s1">&#39;0.1&#39;</span><span class="p">)</span>
  <span class="k">def</span> <span class="nf">create</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;msg&quot;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>
</pre></div>
</div>
<p>This decorator supports three parameters to customize the
endpoint:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">resource&quot;</span></code>: resource id.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">status=200</span></code>: set the HTTP status response code</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">version</span></code>: version</p></li>
</ul>
</section>
<section id="how-to-use-a-custom-api-endpoint-in-a-restcontroller">
<h3><a class="toc-backref" href="#id90" role="doc-backlink">How to use a custom API endpoint in a RESTController?</a><a class="headerlink" href="#how-to-use-a-custom-api-endpoint-in-a-restcontroller" title="Permalink to this heading"></a></h3>
<p>If you don’t have any access restriction you can use <code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code>. If you
have set a permission scope to restrict access to your endpoints,
<code class="docutils literal notranslate"><span class="pre">&#64;Endpoint</span></code> will fail, as it doesn’t know which permission property should be
used. To use a custom endpoint inside a restricted <code class="docutils literal notranslate"><span class="pre">RESTController</span></code> use
<code class="docutils literal notranslate"><span class="pre">&#64;RESTController.Collection</span></code> instead. You can also choose
<code class="docutils literal notranslate"><span class="pre">&#64;RESTController.Resource</span></code> if you have set a <code class="docutils literal notranslate"><span class="pre">RESOURCE_ID</span></code> in your
<code class="docutils literal notranslate"><span class="pre">RESTController</span></code> class.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;ping&#39;</span><span class="p">,</span> <span class="n">Scope</span><span class="o">.</span><span class="n">Ping</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
  <span class="n">RESOURCE_ID</span> <span class="o">=</span> <span class="s1">&#39;ping&#39;</span>

  <span class="nd">@RESTController</span><span class="o">.</span><span class="n">Resource</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">)</span>
  <span class="k">def</span> <span class="nf">some_get_endpoint</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;msg&quot;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>

  <span class="nd">@RESTController</span><span class="o">.</span><span class="n">Collection</span><span class="p">(</span><span class="s1">&#39;POST&#39;</span><span class="p">)</span>
  <span class="k">def</span> <span class="nf">some_post_endpoint</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">data</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;msg&quot;</span><span class="p">:</span> <span class="n">data</span><span class="p">}</span>
</pre></div>
</div>
<p>Both decorators also support five parameters to customize the
endpoint:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">method=&quot;GET&quot;</span></code>: the HTTP method allowed to access this endpoint.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">path=&quot;/&lt;method_name&gt;&quot;</span></code>: the URL path of the endpoint, excluding the
controller URL path prefix.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">status=200</span></code>: set the HTTP status response code</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">query_params=[]</span></code>: list of method parameter names that correspond to URL
query parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">version</span></code>: version</p></li>
</ul>
</section>
<section id="how-to-restrict-access-to-a-controller">
<h3><a class="toc-backref" href="#id91" role="doc-backlink">How to restrict access to a controller?</a><a class="headerlink" href="#how-to-restrict-access-to-a-controller" title="Permalink to this heading"></a></h3>
<p>All controllers require authentication by default.
If you require that the controller can be accessed without authentication,
then you can add the parameter <code class="docutils literal notranslate"><span class="pre">secure=False</span></code> to the controller decorator.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;ping&#39;</span><span class="p">,</span> <span class="n">secure</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
  <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;msg&quot;</span><span class="p">:</span> <span class="s2">&quot;Hello&quot;</span><span class="p">}</span>
</pre></div>
</div>
</section>
<section id="how-to-create-a-dedicated-ui-endpoint-which-uses-the-public-api">
<h3><a class="toc-backref" href="#id92" role="doc-backlink">How to create a dedicated UI endpoint which uses the ‘public’ API?</a><a class="headerlink" href="#how-to-create-a-dedicated-ui-endpoint-which-uses-the-public-api" title="Permalink to this heading"></a></h3>
<p>Sometimes we want to combine multiple calls into one single call
to save bandwidth or for other performance reasons.
In order to achieve that, we first have to create an <code class="docutils literal notranslate"><span class="pre">&#64;UiApiController</span></code> which
is used for endpoints consumed by the UI but that are not part of the
‘public’ API. Let the ui class inherit from the REST controller class.
Now you can use all methods from the api controller.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">UiApiController</span><span class="p">,</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;ping&#39;</span><span class="p">,</span> <span class="n">secure</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>  <span class="c1"># /api/ping</span>
<span class="k">class</span> <span class="nc">Ping</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
  <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_list</span><span class="p">()</span>

  <span class="k">def</span> <span class="nf">_list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>  <span class="c1"># To not get in conflict with the JSON wrapper</span>
    <span class="k">return</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]</span>


<span class="nd">@UiApiController</span><span class="p">(</span><span class="s1">&#39;ping&#39;</span><span class="p">,</span> <span class="n">secure</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>  <span class="c1"># /ui-api/ping</span>
<span class="k">class</span> <span class="nc">PingUi</span><span class="p">(</span><span class="n">Ping</span><span class="p">):</span>
  <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_list</span><span class="p">()</span> <span class="o">+</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]</span>
</pre></div>
</div>
</section>
<section id="how-to-access-the-manager-module-instance-from-a-controller">
<h3><a class="toc-backref" href="#id93" role="doc-backlink">How to access the manager module instance from a controller?</a><a class="headerlink" href="#how-to-access-the-manager-module-instance-from-a-controller" title="Permalink to this heading"></a></h3>
<p>We provide the manager module instance as a global variable that can be
imported in any module.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>
<span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">..</span> <span class="kn">import</span> <span class="n">mgr</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;servers&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Servers</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
  <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Listing available servers&#39;</span><span class="p">)</span>
    <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;servers&#39;</span><span class="p">:</span> <span class="n">mgr</span><span class="o">.</span><span class="n">list_servers</span><span class="p">()}</span>
</pre></div>
</div>
</section>
<section id="how-to-write-a-unit-test-for-a-controller">
<h3><a class="toc-backref" href="#id94" role="doc-backlink">How to write a unit test for a controller?</a><a class="headerlink" href="#how-to-write-a-unit-test-for-a-controller" title="Permalink to this heading"></a></h3>
<p>We provide a test helper class called <code class="docutils literal notranslate"><span class="pre">ControllerTestCase</span></code> to easily create
unit tests for your controller.</p>
<p>If we want to write a unit test for the above <code class="docutils literal notranslate"><span class="pre">Ping</span></code> controller, create a
<code class="docutils literal notranslate"><span class="pre">test_ping.py</span></code> file under the <code class="docutils literal notranslate"><span class="pre">tests</span></code> directory with the following code:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">.helper</span> <span class="kn">import</span> <span class="n">ControllerTestCase</span>
<span class="kn">from</span> <span class="nn">.controllers.ping</span> <span class="kn">import</span> <span class="n">Ping</span>


<span class="k">class</span> <span class="nc">PingTest</span><span class="p">(</span><span class="n">ControllerTestCase</span><span class="p">):</span>
    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">setup_test</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>
        <span class="n">cp_config</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;tools.authenticate.on&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
        <span class="bp">cls</span><span class="o">.</span><span class="n">setup_controllers</span><span class="p">([</span><span class="n">Ping</span><span class="p">],</span> <span class="n">cp_config</span><span class="o">=</span><span class="n">cp_config</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">test_ping</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_get</span><span class="p">(</span><span class="s2">&quot;/api/ping&quot;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertStatus</span><span class="p">(</span><span class="mi">200</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertJsonBody</span><span class="p">({</span><span class="s1">&#39;msg&#39;</span><span class="p">:</span> <span class="s1">&#39;Hello&#39;</span><span class="p">})</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">ControllerTestCase</span></code> class starts by initializing a CherryPy webserver.
Then it will call the <code class="docutils literal notranslate"><span class="pre">setup_test()</span></code> class method where we can explicitly
load the controllers that we want to test. In the above example we are only
loading the <code class="docutils literal notranslate"><span class="pre">Ping</span></code> controller. We can also provide <code class="docutils literal notranslate"><span class="pre">cp_config</span></code> in order to
update the controller’s cherrypy config (e.g. enable authentication as shown in the example).</p>
</section>
<section id="how-to-update-or-create-new-dashboards-in-grafana">
<h3><a class="toc-backref" href="#id95" role="doc-backlink">How to update or create new dashboards in grafana?</a><a class="headerlink" href="#how-to-update-or-create-new-dashboards-in-grafana" title="Permalink to this heading"></a></h3>
<p>We are using <code class="docutils literal notranslate"><span class="pre">jsonnet</span></code> and <code class="docutils literal notranslate"><span class="pre">grafonnet-lib</span></code> to write code for the grafana dashboards.
All the dashboards are written inside <code class="docutils literal notranslate"><span class="pre">grafana_dashboards.jsonnet</span></code> file in the
monitoring/grafana/dashboards/jsonnet directory.</p>
<p>We generate the dashboard json files directly from this jsonnet file by running this
command in the grafana/dashboards directory:
<code class="docutils literal notranslate"><span class="pre">jsonnet</span> <span class="pre">-m</span> <span class="pre">.</span> <span class="pre">jsonnet/grafana_dashboards.jsonnet</span></code>.
(For the above command to succeed we need <code class="docutils literal notranslate"><span class="pre">jsonnet</span></code> package installed and <code class="docutils literal notranslate"><span class="pre">grafonnet-lib</span></code>
directory cloned in our machine. Please refer -
<code class="docutils literal notranslate"><span class="pre">https://grafana.github.io/grafonnet-lib/getting-started/</span></code> in case you have some trouble.)</p>
<p>To update an existing grafana dashboard or to create a new one, we need to update
the <code class="docutils literal notranslate"><span class="pre">grafana_dashboards.jsonnet</span></code> file and generate the new/updated json files using the
above mentioned command. For people who are not familiar with grafonnet or jsonnet implementation
can follow this doc - <code class="docutils literal notranslate"><span class="pre">https://grafana.github.io/grafonnet-lib/</span></code>.</p>
<p>Example grafana dashboard in jsonnet format:</p>
<p>To specify the grafana dashboard properties such as title, uid etc we can create a local function -</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">local</span> <span class="n">dashboardSchema</span><span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">uid</span><span class="p">,</span> <span class="n">time_from</span><span class="p">,</span> <span class="n">refresh</span><span class="p">,</span> <span class="n">schemaVersion</span><span class="p">,</span> <span class="n">tags</span><span class="p">,</span><span class="n">timezone</span><span class="p">,</span> <span class="n">timepicker</span><span class="p">)</span>
</pre></div>
</div>
<p>To add a graph panel we can specify the graph schema in a local function such as -</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">local</span> <span class="n">graphPanelSchema</span><span class="p">(</span><span class="n">title</span><span class="p">,</span> <span class="n">nullPointMode</span><span class="p">,</span> <span class="n">stack</span><span class="p">,</span> <span class="n">formatY1</span><span class="p">,</span> <span class="n">formatY2</span><span class="p">,</span> <span class="n">labelY1</span><span class="p">,</span> <span class="n">labelY2</span><span class="p">,</span> <span class="nb">min</span><span class="p">,</span> <span class="n">fill</span><span class="p">,</span> <span class="n">datasource</span><span class="p">)</span>
</pre></div>
</div>
<p>and then use these functions inside the dashboard definition like -</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="n">radosgw</span><span class="o">-</span><span class="n">sync</span><span class="o">-</span><span class="n">overview</span><span class="o">.</span><span class="n">json</span><span class="p">:</span> <span class="o">//</span><span class="n">json</span> <span class="n">file</span> <span class="n">name</span> <span class="n">to</span> <span class="n">be</span> <span class="n">generated</span>

    <span class="n">dashboardSchema</span><span class="p">(</span>
      <span class="s1">&#39;RGW Sync Overview&#39;</span><span class="p">,</span> <span class="s1">&#39;rgw-sync-overview&#39;</span><span class="p">,</span> <span class="s1">&#39;now-1h&#39;</span><span class="p">,</span> <span class="s1">&#39;15s&#39;</span><span class="p">,</span> <span class="o">..</span><span class="p">,</span> <span class="o">..</span><span class="p">,</span> <span class="o">..</span>
    <span class="p">)</span>

    <span class="o">.</span><span class="n">addPanels</span><span class="p">([</span>
      <span class="n">graphPanelSchema</span><span class="p">(</span>
        <span class="s1">&#39;Replication (throughput) from Source Zone&#39;</span><span class="p">,</span> <span class="s1">&#39;Bps&#39;</span><span class="p">,</span> <span class="n">null</span><span class="p">,</span> <span class="o">..</span><span class="p">,</span> <span class="o">..</span><span class="p">,</span> <span class="o">..</span><span class="p">)</span>
    <span class="p">])</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The valid grafonnet-lib attributes can be found here - <code class="docutils literal notranslate"><span class="pre">https://grafana.github.io/grafonnet-lib/api-docs/</span></code>.</p>
</section>
<section id="how-to-listen-for-manager-notifications-in-a-controller">
<h3><a class="toc-backref" href="#id96" role="doc-backlink">How to listen for manager notifications in a controller?</a><a class="headerlink" href="#how-to-listen-for-manager-notifications-in-a-controller" title="Permalink to this heading"></a></h3>
<p>The manager notifies the modules of several types of cluster events, such
as cluster logging event, etc…</p>
<p>Each module has a “global” handler function called <code class="docutils literal notranslate"><span class="pre">notify</span></code> that the manager
calls to notify the module. But this handler function must not block or spend
too much time processing the event notification.
For this reason we provide a notification queue that controllers can register
themselves with to receive cluster notifications.</p>
<p>The example below represents a controller that implements a very simple live
log viewer page:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">collections</span>

<span class="kn">import</span> <span class="nn">cherrypy</span>

<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">BaseController</span><span class="p">,</span> <span class="n">NotificationQueue</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;livelog&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">LiveLog</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
    <span class="n">log_buffer</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">deque</span><span class="p">(</span><span class="n">maxlen</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">LiveLog</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>
        <span class="n">NotificationQueue</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">,</span> <span class="s1">&#39;clog&#39;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">log</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">log_struct</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">log_buffer</span><span class="o">.</span><span class="n">appendleft</span><span class="p">(</span><span class="n">log_struct</span><span class="p">)</span>

    <span class="nd">@cherrypy</span><span class="o">.</span><span class="n">expose</span>
    <span class="k">def</span> <span class="nf">default</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">ret</span> <span class="o">=</span> <span class="s1">&#39;&lt;html&gt;&lt;meta http-equiv=&quot;refresh&quot; content=&quot;2&quot; /&gt;&lt;body&gt;&#39;</span>
        <span class="k">for</span> <span class="n">l</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">log_buffer</span><span class="p">:</span>
            <span class="n">ret</span> <span class="o">+=</span> <span class="s2">&quot;</span><span class="si">{}</span><span class="s2">&lt;br&gt;&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">l</span><span class="p">)</span>
        <span class="n">ret</span> <span class="o">+=</span> <span class="s2">&quot;&lt;/body&gt;&lt;/html&gt;&quot;</span>
        <span class="k">return</span> <span class="n">ret</span>
</pre></div>
</div>
<p>As you can see above, the <code class="docutils literal notranslate"><span class="pre">NotificationQueue</span></code> class provides a register
method that receives the function as its first argument, and receives the
“notification type” as the second argument.
You can omit the second argument of the <code class="docutils literal notranslate"><span class="pre">register</span></code> method, and in that case
you are registering to listen all notifications of any type.</p>
<p>Here is an list of notification types (these might change in the future) that
can be used:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">clog</span></code>: cluster log notifications</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">command</span></code>: notification when a command issued by <code class="docutils literal notranslate"><span class="pre">MgrModule.send_command</span></code>
completes</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">perf_schema_update</span></code>: perf counters schema update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mon_map</span></code>: monitor map update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fs_map</span></code>: cephfs map update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">osd_map</span></code>: OSD map update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">service_map</span></code>: services (RGW, RBD-Mirror, etc.) map update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mon_status</span></code>: monitor status regular update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">health</span></code>: health status regular update</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pg_summary</span></code>: regular update of PG status information</p></li>
</ul>
</section>
<section id="how-to-write-a-unit-test-when-a-controller-accesses-a-ceph-module">
<h3><a class="toc-backref" href="#id97" role="doc-backlink">How to write a unit test when a controller accesses a Ceph module?</a><a class="headerlink" href="#how-to-write-a-unit-test-when-a-controller-accesses-a-ceph-module" title="Permalink to this heading"></a></h3>
<p>Consider the following example that implements a controller that retrieves the
list of RBD images of the <code class="docutils literal notranslate"><span class="pre">rbd</span></code> pool:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">rbd</span>
<span class="kn">from</span> <span class="nn">..</span> <span class="kn">import</span> <span class="n">mgr</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;rbdimages&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">RbdImages</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">ioctx</span> <span class="o">=</span> <span class="n">mgr</span><span class="o">.</span><span class="n">rados</span><span class="o">.</span><span class="n">open_ioctx</span><span class="p">(</span><span class="s1">&#39;rbd&#39;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">rbd</span> <span class="o">=</span> <span class="n">rbd</span><span class="o">.</span><span class="n">RBD</span><span class="p">()</span>

    <span class="k">def</span> <span class="nf">list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">[{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="n">n</span><span class="p">}</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">rbd</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">ioctx</span><span class="p">)]</span>
</pre></div>
</div>
<p>In the example above, we want to mock the return value of the <code class="docutils literal notranslate"><span class="pre">rbd.list</span></code>
function, so that we can test the JSON response of the controller.</p>
<p>The unit test code will look like the following:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">mock</span>
<span class="kn">from</span> <span class="nn">.helper</span> <span class="kn">import</span> <span class="n">ControllerTestCase</span>


<span class="k">class</span> <span class="nc">RbdImagesTest</span><span class="p">(</span><span class="n">ControllerTestCase</span><span class="p">):</span>
    <span class="nd">@mock</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="s1">&#39;rbd.RBD.list&#39;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">test_list</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">rbd_list_mock</span><span class="p">):</span>
        <span class="n">rbd_list_mock</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;img1&#39;</span><span class="p">,</span> <span class="s1">&#39;img2&#39;</span><span class="p">]</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_get</span><span class="p">(</span><span class="s1">&#39;/api/rbdimages&#39;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertJsonBody</span><span class="p">([{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;img1&#39;</span><span class="p">},</span> <span class="p">{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;img2&#39;</span><span class="p">}])</span>
</pre></div>
</div>
</section>
<section id="how-to-add-a-new-configuration-setting">
<h3><a class="toc-backref" href="#id98" role="doc-backlink">How to add a new configuration setting?</a><a class="headerlink" href="#how-to-add-a-new-configuration-setting" title="Permalink to this heading"></a></h3>
<p>If you need to store some configuration setting for a new feature, we already
provide an easy mechanism for you to specify/use the new config setting.</p>
<p>For instance, if you want to add a new configuration setting to hold the
email address of the dashboard admin, just add a setting name as a class
attribute to the <code class="docutils literal notranslate"><span class="pre">Options</span></code> class in the <code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># ...</span>
<span class="k">class</span> <span class="nc">Options</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
  <span class="c1"># ...</span>

  <span class="n">ADMIN_EMAIL_ADDRESS</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;admin@admin.com&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
</pre></div>
</div>
<p>The value of the class attribute is a pair composed by the default value for that
setting, and the python type of the value.</p>
<p>By declaring the <code class="docutils literal notranslate"><span class="pre">ADMIN_EMAIL_ADDRESS</span></code> class attribute, when you restart the
dashboard module, you will automatically gain two additional CLI commands to
get and set that setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ceph dashboard get-admin-email-address
$ ceph dashboard set-admin-email-address &lt;value&gt;
</pre></div>
</div>
<p>To access, or modify the config setting value from your Python code, either
inside a controller or anywhere else, you just need to import the <code class="docutils literal notranslate"><span class="pre">Settings</span></code>
class and access it like this:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">settings</span> <span class="kn">import</span> <span class="n">Settings</span>

<span class="c1"># ...</span>
<span class="n">tmp_var</span> <span class="o">=</span> <span class="n">Settings</span><span class="o">.</span><span class="n">ADMIN_EMAIL_ADDRESS</span>

<span class="c1"># ....</span>
<span class="n">Settings</span><span class="o">.</span><span class="n">ADMIN_EMAIL_ADDRESS</span> <span class="o">=</span> <span class="s1">&#39;myemail@admin.com&#39;</span>
</pre></div>
</div>
<p>The settings management implementation will make sure that if you change a
setting value from the Python code you will see that change when accessing
that setting from the CLI and vice-versa.</p>
</section>
<section id="how-to-run-a-controller-read-write-operation-asynchronously">
<h3><a class="toc-backref" href="#id99" role="doc-backlink">How to run a controller read-write operation asynchronously?</a><a class="headerlink" href="#how-to-run-a-controller-read-write-operation-asynchronously" title="Permalink to this heading"></a></h3>
<p>Some controllers might need to execute operations that alter the state of the
Ceph cluster. These operations might take some time to execute and to maintain
a good user experience in the Web UI, we need to run those operations
asynchronously and return immediately to frontend some information that the
operations are running in the background.</p>
<p>To help in the development of the above scenario we added the support for
asynchronous tasks. To trigger the execution of an asynchronous task we must
use the following class method of the <code class="docutils literal notranslate"><span class="pre">TaskManager</span></code> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">TaskManager</span>
<span class="c1"># ...</span>
<span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="n">func</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">name</span></code> is a string that can be used to group tasks. For instance
for RBD image creation tasks we could specify <code class="docutils literal notranslate"><span class="pre">&quot;rbd/create&quot;</span></code> as the
name, or similarly <code class="docutils literal notranslate"><span class="pre">&quot;rbd/remove&quot;</span></code> for RBD image removal tasks.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">metadata</span></code> is a dictionary where we can store key-value pairs that
characterize the task. For instance, when creating a task for creating
RBD images we can specify the metadata argument as
<code class="docutils literal notranslate"><span class="pre">{'pool_name':</span> <span class="pre">&quot;rbd&quot;,</span> <span class="pre">image_name':</span> <span class="pre">&quot;test-img&quot;}</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">func</span></code> is the python function that implements the operation code, which
will be executed asynchronously.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">args</span></code> and <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> are the positional and named arguments that will be
passed to <code class="docutils literal notranslate"><span class="pre">func</span></code> when the task manager starts its execution.</p></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code> method triggers the asynchronous execution of function
<code class="docutils literal notranslate"><span class="pre">func</span></code> and returns a <code class="docutils literal notranslate"><span class="pre">Task</span></code> object.
The <code class="docutils literal notranslate"><span class="pre">Task</span></code> provides the public method <code class="docutils literal notranslate"><span class="pre">Task.wait(timeout)</span></code>, which can be
used to wait for the task to complete up to a timeout defined in seconds and
provided as an argument. If no argument is provided the <code class="docutils literal notranslate"><span class="pre">wait</span></code> method
blocks until the task is finished.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Task.wait</span></code> is very useful for tasks that usually are fast to execute but
that sometimes may take a long time to run.
The return value of the <code class="docutils literal notranslate"><span class="pre">Task.wait</span></code> method is a pair <code class="docutils literal notranslate"><span class="pre">(state,</span> <span class="pre">value)</span></code>
where <code class="docutils literal notranslate"><span class="pre">state</span></code> is a string with following possible values:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">VALUE_DONE</span> <span class="pre">=</span> <span class="pre">&quot;done&quot;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">VALUE_EXECUTING</span> <span class="pre">=</span> <span class="pre">&quot;executing&quot;</span></code></p></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">value</span></code> will store the result of the execution of function <code class="docutils literal notranslate"><span class="pre">func</span></code> if
<code class="docutils literal notranslate"><span class="pre">state</span> <span class="pre">==</span> <span class="pre">VALUE_DONE</span></code>. If <code class="docutils literal notranslate"><span class="pre">state</span> <span class="pre">==</span> <span class="pre">VALUE_EXECUTING</span></code> then
<code class="docutils literal notranslate"><span class="pre">value</span> <span class="pre">==</span> <span class="pre">None</span></code>.</p>
<p>The pair <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">metadata)</span></code> should unequivocally identify the task being
run, which means that if you try to trigger a new task that matches the same
<code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">metadata)</span></code> pair of the currently running task, then the new task
is not created and you get the task object of the current running task.</p>
<p>For instance, consider the following example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">task1</span> <span class="o">=</span> <span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;dummy/task&quot;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;attr&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">},</span> <span class="n">func</span><span class="p">)</span>
<span class="n">task2</span> <span class="o">=</span> <span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;dummy/task&quot;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;attr&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">},</span> <span class="n">func</span><span class="p">)</span>
</pre></div>
</div>
<p>If the second call to <code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code> executes while the first task is
still executing then it will return the same task object:
<code class="docutils literal notranslate"><span class="pre">assert</span> <span class="pre">task1</span> <span class="pre">==</span> <span class="pre">task2</span></code>.</p>
</section>
<section id="how-to-get-the-list-of-executing-and-finished-asynchronous-tasks">
<h3><a class="toc-backref" href="#id100" role="doc-backlink">How to get the list of executing and finished asynchronous tasks?</a><a class="headerlink" href="#how-to-get-the-list-of-executing-and-finished-asynchronous-tasks" title="Permalink to this heading"></a></h3>
<p>The list of executing and finished tasks is included in the <code class="docutils literal notranslate"><span class="pre">Summary</span></code>
controller, which is already polled every 5 seconds by the dashboard frontend.
But we also provide a dedicated controller to get the same list of executing
and finished tasks.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Task</span></code> controller exposes the <code class="docutils literal notranslate"><span class="pre">/api/task</span></code> endpoint that returns the
list of executing and finished tasks. This endpoint accepts the <code class="docutils literal notranslate"><span class="pre">name</span></code>
parameter that accepts a glob expression as its value.
For instance, an HTTP GET request of the URL <code class="docutils literal notranslate"><span class="pre">/api/task?name=rbd/*</span></code>
will return all executing and finished tasks which name starts with <code class="docutils literal notranslate"><span class="pre">rbd/</span></code>.</p>
<p>To prevent the finished tasks list from growing unbounded, we will always
maintain the 10 most recent finished tasks, and the remaining older finished
tasks will be removed when reaching a TTL of 1 minute. The TTL is calculated
using the timestamp when the task finished its execution. After a minute, when
the finished task information is retrieved, either by the summary controller or
by the task controller, it is automatically deleted from the list and it will
not be included in further task queries.</p>
<p>Each executing task is represented by the following dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s2">&quot;name&quot;</span><span class="p">,</span>  <span class="c1"># str</span>
  <span class="s1">&#39;metadata&#39;</span><span class="p">:</span> <span class="p">{</span> <span class="p">},</span>  <span class="c1"># dict</span>
  <span class="s1">&#39;begin_time&#39;</span><span class="p">:</span> <span class="s2">&quot;2018-03-14T15:31:38.423605Z&quot;</span><span class="p">,</span>  <span class="c1"># str (ISO 8601 format)</span>
  <span class="s1">&#39;progress&#39;</span><span class="p">:</span> <span class="mi">0</span>  <span class="c1"># int (percentage)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Each finished task is represented by the following dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s2">&quot;name&quot;</span><span class="p">,</span>  <span class="c1"># str</span>
  <span class="s1">&#39;metadata&#39;</span><span class="p">:</span> <span class="p">{</span> <span class="p">},</span>  <span class="c1"># dict</span>
  <span class="s1">&#39;begin_time&#39;</span><span class="p">:</span> <span class="s2">&quot;2018-03-14T15:31:38.423605Z&quot;</span><span class="p">,</span>  <span class="c1"># str (ISO 8601 format)</span>
  <span class="s1">&#39;end_time&#39;</span><span class="p">:</span> <span class="s2">&quot;2018-03-14T15:31:39.423605Z&quot;</span><span class="p">,</span>  <span class="c1"># str (ISO 8601 format)</span>
  <span class="s1">&#39;duration&#39;</span><span class="p">:</span> <span class="mf">0.0</span><span class="p">,</span>  <span class="c1"># float</span>
  <span class="s1">&#39;progress&#39;</span><span class="p">:</span> <span class="mi">0</span>  <span class="c1"># int (percentage)</span>
  <span class="s1">&#39;success&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>  <span class="c1"># bool</span>
  <span class="s1">&#39;ret_value&#39;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># object, populated only if &#39;success&#39; == True</span>
  <span class="s1">&#39;exception&#39;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># str, populated only if &#39;success&#39; == False</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="how-to-use-asynchronous-apis-with-asynchronous-tasks">
<h3><a class="toc-backref" href="#id101" role="doc-backlink">How to use asynchronous APIs with asynchronous tasks?</a><a class="headerlink" href="#how-to-use-asynchronous-apis-with-asynchronous-tasks" title="Permalink to this heading"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code> method as described in a previous section, is well
suited for calling blocking functions, as it runs the function inside a newly
created thread. But sometimes we want to call some function of an API that is
already asynchronous by nature.</p>
<p>For these cases we want to avoid creating a new thread for just running a
non-blocking function, and want to leverage the asynchronous nature of the
function. The <code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code> is already prepared to be used with
non-blocking functions by passing an object of the type <code class="docutils literal notranslate"><span class="pre">TaskExecutor</span></code> as an
additional parameter called <code class="docutils literal notranslate"><span class="pre">executor</span></code>. The full method signature of
<code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="n">func</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">kwargs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">executor</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">TaskExecutor</span></code> class is responsible for code that executes a given task
function, and defines three methods that can be overridden by
subclasses:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">init</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">start</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">finish</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ret_value</span><span class="p">,</span> <span class="n">exception</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">init</span></code> method is called before the running the task function, and
receives the task object (of class <code class="docutils literal notranslate"><span class="pre">Task</span></code>).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">start</span></code> method runs the task function. The default implementation is to
run the task function in the current thread context.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">finish</span></code> method should be called when the task function finishes with
either the <code class="docutils literal notranslate"><span class="pre">ret_value</span></code> populated with the result of the execution, or with
an exception object in the case that execution raised an exception.</p>
<p>To leverage the asynchronous nature of a non-blocking function, the developer
should implement a custom executor by creating a subclass of the
<code class="docutils literal notranslate"><span class="pre">TaskExecutor</span></code> class, and provide an instance of the custom executor class
as the <code class="docutils literal notranslate"><span class="pre">executor</span></code> parameter of the <code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code>.</p>
<p>To better understand the expressive power of executors, we write a full example
of use a custom executor to execute the <code class="docutils literal notranslate"><span class="pre">MgrModule.send_command</span></code> asynchronous
function:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">json</span>
<span class="kn">from</span> <span class="nn">mgr_module</span> <span class="kn">import</span> <span class="n">CommandResult</span>
<span class="kn">from</span> <span class="nn">..</span> <span class="kn">import</span> <span class="n">mgr</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span><span class="p">,</span> <span class="n">NotificationQueue</span><span class="p">,</span> \
                    <span class="n">TaskManager</span><span class="p">,</span> <span class="n">TaskExecutor</span>


<span class="k">class</span> <span class="nc">SendCommandExecutor</span><span class="p">(</span><span class="n">TaskExecutor</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">SendCommandExecutor</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">tag</span> <span class="o">=</span> <span class="kc">None</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">result</span> <span class="o">=</span> <span class="kc">None</span>

    <span class="k">def</span> <span class="nf">init</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">task</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">SendCommandExecutor</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">task</span><span class="p">)</span>

        <span class="c1"># we need to listen for &#39;command&#39; events to know when the command</span>
        <span class="c1"># finishes</span>
        <span class="n">NotificationQueue</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_handler</span><span class="p">,</span> <span class="s1">&#39;command&#39;</span><span class="p">)</span>

        <span class="c1"># store the CommandResult object to retrieve the results</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">task</span><span class="o">.</span><span class="n">fn_args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">task</span><span class="o">.</span><span class="n">fn_args</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">4</span><span class="p">:</span>
            <span class="c1"># the user specified a tag for the command, so let&#39;s use it</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">tag</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">task</span><span class="o">.</span><span class="n">fn_args</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="c1"># let&#39;s generate a unique tag for the command</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">tag</span> <span class="o">=</span> <span class="s1">&#39;send_command_</span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="nb">id</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">task</span><span class="o">.</span><span class="n">fn_args</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_handler</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">data</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">tag</span><span class="p">:</span>
            <span class="c1"># the command has finished, notifying the task with the result</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">finish</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">result</span><span class="o">.</span><span class="n">wait</span><span class="p">(),</span> <span class="kc">None</span><span class="p">)</span>
            <span class="c1"># deregister listener to avoid memory leaks</span>
            <span class="n">NotificationQueue</span><span class="o">.</span><span class="n">deregister</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_handler</span><span class="p">,</span> <span class="s1">&#39;command&#39;</span><span class="p">)</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;test&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Test</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">_run_task</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">osd_id</span><span class="p">):</span>
        <span class="n">task</span> <span class="o">=</span> <span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;test/task&quot;</span><span class="p">,</span> <span class="p">{},</span> <span class="n">mgr</span><span class="o">.</span><span class="n">send_command</span><span class="p">,</span>
                               <span class="p">[</span><span class="n">CommandResult</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">),</span> <span class="s1">&#39;osd&#39;</span><span class="p">,</span> <span class="n">osd_id</span><span class="p">,</span>
                                <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s1">&#39;prefix&#39;</span><span class="p">:</span> <span class="s1">&#39;perf histogram dump&#39;</span><span class="p">})],</span>
                               <span class="n">executor</span><span class="o">=</span><span class="n">SendCommandExecutor</span><span class="p">())</span>
        <span class="k">return</span> <span class="n">task</span><span class="o">.</span><span class="n">wait</span><span class="p">(</span><span class="mf">1.0</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">osd_id</span><span class="p">):</span>
        <span class="n">status</span><span class="p">,</span> <span class="n">value</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_run_task</span><span class="p">(</span><span class="n">osd_id</span><span class="p">)</span>
        <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;status&#39;</span><span class="p">:</span> <span class="n">status</span><span class="p">,</span> <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="n">value</span><span class="p">}</span>
</pre></div>
</div>
<p>The above <code class="docutils literal notranslate"><span class="pre">SendCommandExecutor</span></code> executor class can be used for any call to
<code class="docutils literal notranslate"><span class="pre">MgrModule.send_command</span></code>. This means that we should need just one custom
executor class implementation for each non-blocking API that we use in our
controllers.</p>
<p>The default executor, used when no executor object is passed to
<code class="docutils literal notranslate"><span class="pre">TaskManager.run</span></code>, is the <code class="docutils literal notranslate"><span class="pre">ThreadedExecutor</span></code>. You can check its
implementation in the <code class="docutils literal notranslate"><span class="pre">tools.py</span></code> file.</p>
</section>
<section id="how-to-update-the-execution-progress-of-an-asynchronous-task">
<h3><a class="toc-backref" href="#id102" role="doc-backlink">How to update the execution progress of an asynchronous task?</a><a class="headerlink" href="#how-to-update-the-execution-progress-of-an-asynchronous-task" title="Permalink to this heading"></a></h3>
<p>The asynchronous tasks infrastructure provides support for updating the
execution progress of an executing task.
The progress can be updated from within the code the task is executing, which
usually is the place where we have the progress information available.</p>
<p>To update the progress from within the task code, the <code class="docutils literal notranslate"><span class="pre">TaskManager</span></code> class
provides a method to retrieve the current task object:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TaskManager</span><span class="o">.</span><span class="n">current_task</span><span class="p">()</span>
</pre></div>
</div>
<p>The above method is only available when using the default executor
<code class="docutils literal notranslate"><span class="pre">ThreadedExecutor</span></code> for executing the task.
The <code class="docutils literal notranslate"><span class="pre">current_task()</span></code> method returns the current <code class="docutils literal notranslate"><span class="pre">Task</span></code> object. The
<code class="docutils literal notranslate"><span class="pre">Task</span></code> object provides two public methods to update the execution progress
value: the <code class="docutils literal notranslate"><span class="pre">set_progress(percentage)</span></code>, and the <code class="docutils literal notranslate"><span class="pre">inc_progress(delta)</span></code>
methods.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">set_progress</span></code> method receives as argument an integer value representing
the absolute percentage that we want to set to the task.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">inc_progress</span></code> method receives as argument an integer value representing
the delta we want to increment to the current execution progress percentage.</p>
<p>Take the following example of a controller that triggers a new task and
updates its progress:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">random</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">cherrypy</span>
<span class="kn">from</span> <span class="nn">..tools</span> <span class="kn">import</span> <span class="n">TaskManager</span><span class="p">,</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">BaseController</span>


<span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;dummy_task&#39;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">DummyTask</span><span class="p">(</span><span class="n">BaseController</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">_dummy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">top</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randrange</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">top</span><span class="p">):</span>
            <span class="n">TaskManager</span><span class="o">.</span><span class="n">current_task</span><span class="p">()</span><span class="o">.</span><span class="n">set_progress</span><span class="p">(</span><span class="n">i</span><span class="o">*</span><span class="mi">100</span><span class="o">/</span><span class="n">top</span><span class="p">)</span>
            <span class="c1"># or TaskManager.current_task().inc_progress(100/top)</span>
            <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
        <span class="k">return</span> <span class="s2">&quot;finished&quot;</span>

    <span class="nd">@cherrypy</span><span class="o">.</span><span class="n">expose</span>
    <span class="nd">@cherrypy</span><span class="o">.</span><span class="n">tools</span><span class="o">.</span><span class="n">json_out</span><span class="p">()</span>
    <span class="k">def</span> <span class="nf">default</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">task</span> <span class="o">=</span> <span class="n">TaskManager</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;dummy/task&quot;</span><span class="p">,</span> <span class="p">{},</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dummy</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">task</span><span class="o">.</span><span class="n">wait</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>  <span class="c1"># wait for five seconds</span>
</pre></div>
</div>
</section>
<section id="how-to-deal-with-asynchronous-tasks-in-the-front-end">
<h3><a class="toc-backref" href="#id103" role="doc-backlink">How to deal with asynchronous tasks in the front-end?</a><a class="headerlink" href="#how-to-deal-with-asynchronous-tasks-in-the-front-end" title="Permalink to this heading"></a></h3>
<p>All executing and most recently finished asynchronous tasks are displayed on
“Background-Tasks” and if finished on “Recent-Notifications” in the menu bar.
For each task a operation name for three states (running, success and failure),
a function that tells who is involved and error descriptions, if any, have to
be provided. This can be  achieved by appending
<code class="docutils literal notranslate"><span class="pre">TaskManagerMessageService.messages</span></code>.  This has to be done to achieve
consistency among all tasks and states.</p>
<dl class="simple">
<dt>Operation Object</dt><dd><p>Ensures consistency among all tasks. It consists of three verbs for each
different state f.e.
<code class="docutils literal notranslate"><span class="pre">{running:</span> <span class="pre">'Creating',</span> <span class="pre">failure:</span> <span class="pre">'create',</span> <span class="pre">success:</span> <span class="pre">'Created'}</span></code>.</p>
</dd>
</dl>
<ol class="arabic simple">
<li><p>Put running operations in present participle f.e. <code class="docutils literal notranslate"><span class="pre">'Updating'</span></code>.</p></li>
<li><p>Failed messages always start with <code class="docutils literal notranslate"><span class="pre">'Failed</span> <span class="pre">to</span> <span class="pre">'</span></code> and should be continued
with the operation in present tense f.e. <code class="docutils literal notranslate"><span class="pre">'update'</span></code>.</p></li>
<li><p>Put successful operations in past tense f.e. <code class="docutils literal notranslate"><span class="pre">'Updated'</span></code>.</p></li>
</ol>
<dl class="simple">
<dt>Involves Function</dt><dd><p>Ensures consistency among all messages of a task, it resembles who’s
involved by the operation. It’s a function that returns a string which
takes the metadata from the task to return f.e.
<code class="docutils literal notranslate"><span class="pre">&quot;RBD</span> <span class="pre">'somePool/someImage'&quot;</span></code>.</p>
</dd>
</dl>
<p>Both combined create the following messages:</p>
<ul class="simple">
<li><p>Failure =&gt; <code class="docutils literal notranslate"><span class="pre">&quot;Failed</span> <span class="pre">to</span> <span class="pre">create</span> <span class="pre">RBD</span> <span class="pre">'somePool/someImage'&quot;</span></code></p></li>
<li><p>Running =&gt; <code class="docutils literal notranslate"><span class="pre">&quot;Creating</span> <span class="pre">RBD</span> <span class="pre">'somePool/someImage'&quot;</span></code></p></li>
<li><p>Success =&gt; <code class="docutils literal notranslate"><span class="pre">&quot;Created</span> <span class="pre">RBD</span> <span class="pre">'somePool/someImage'&quot;</span></code></p></li>
</ul>
<p>For automatic task handling use <code class="docutils literal notranslate"><span class="pre">TaskWrapperService.wrapTaskAroundCall</span></code>.</p>
<p>If for some reason <code class="docutils literal notranslate"><span class="pre">wrapTaskAroundCall</span></code> is not working for you,
you have to subscribe to your asynchronous task manually through
<code class="docutils literal notranslate"><span class="pre">TaskManagerService.subscribe</span></code>, and provide it with a callback,
in case of a success to notify the user. A notification can
be triggered with <code class="docutils literal notranslate"><span class="pre">NotificationService.notifyTask</span></code>. It will use
<code class="docutils literal notranslate"><span class="pre">TaskManagerMessageService.messages</span></code> to display a message based on the state
of a task.</p>
<p>Notifications of API errors are handled by <code class="docutils literal notranslate"><span class="pre">ApiInterceptorService</span></code>.</p>
<p>Usage example:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="k">export</span><span class="w"> </span><span class="kd">class</span><span class="w"> </span><span class="nx">TaskManagerMessageService</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="c1">// ...</span>
<span class="w">  </span><span class="nx">messages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="c1">// Messages for task &#39;rbd/create&#39;</span>
<span class="w">    </span><span class="s1">&#39;rbd/create&#39;</span><span class="o">:</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="nx">TaskManagerMessage</span><span class="p">(</span>
<span class="w">      </span><span class="c1">// Message prefixes</span>
<span class="w">      </span><span class="p">[</span><span class="s1">&#39;create&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;Creating&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;Created&#39;</span><span class="p">],</span>
<span class="w">      </span><span class="c1">// Message suffix</span>
<span class="w">      </span><span class="p">(</span><span class="nx">metadata</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="sb">`RBD &#39;</span><span class="si">${</span><span class="nx">metadata</span><span class="p">.</span><span class="nx">pool_name</span><span class="si">}</span><span class="sb">/</span><span class="si">${</span><span class="nx">metadata</span><span class="p">.</span><span class="nx">image_name</span><span class="si">}</span><span class="sb">&#39;`</span><span class="p">,</span>
<span class="w">      </span><span class="p">(</span><span class="nx">metadata</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">({</span>
<span class="w">        </span><span class="c1">// Error code and description</span>
<span class="w">        </span><span class="s1">&#39;17&#39;</span><span class="o">:</span><span class="w"> </span><span class="sb">`Name is already used by RBD &#39;</span><span class="si">${</span><span class="nx">metadata</span><span class="p">.</span><span class="nx">pool_name</span><span class="si">}</span><span class="sb">/</span><span class="si">${</span>
<span class="w">               </span><span class="nx">metadata</span><span class="p">.</span><span class="nx">image_name</span><span class="si">}</span><span class="sb">&#39;.`</span>
<span class="w">      </span><span class="p">})</span>
<span class="w">    </span><span class="p">),</span>
<span class="w">    </span><span class="c1">// ...</span>
<span class="w">  </span><span class="p">};</span>
<span class="w">  </span><span class="c1">// ...</span>
<span class="p">}</span>

<span class="k">export</span><span class="w"> </span><span class="kd">class</span><span class="w"> </span><span class="nx">RBDFormComponent</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="c1">// ...</span>
<span class="w">  </span><span class="nx">createAction</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="kd">const</span><span class="w"> </span><span class="nx">request</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">this</span><span class="p">.</span><span class="nx">createRequest</span><span class="p">();</span>
<span class="w">    </span><span class="c1">// Subscribes to &#39;call&#39; with submitted &#39;task&#39; and handles notifications</span>
<span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="k">this</span><span class="p">.</span><span class="nx">taskWrapper</span><span class="p">.</span><span class="nx">wrapTaskAroundCall</span><span class="p">({</span>
<span class="w">      </span><span class="nx">task</span><span class="o">:</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="nx">FinishedTask</span><span class="p">(</span><span class="s1">&#39;rbd/create&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">{</span>
<span class="w">        </span><span class="nx">pool_name</span><span class="o">:</span><span class="w"> </span><span class="nx">request</span><span class="p">.</span><span class="nx">pool_name</span><span class="p">,</span>
<span class="w">        </span><span class="nx">image_name</span><span class="o">:</span><span class="w"> </span><span class="nx">request</span><span class="p">.</span><span class="nx">name</span>
<span class="w">      </span><span class="p">}),</span>
<span class="w">      </span><span class="nx">call</span><span class="o">:</span><span class="w"> </span><span class="k">this</span><span class="p">.</span><span class="nx">rbdService</span><span class="p">.</span><span class="nx">create</span><span class="p">(</span><span class="nx">request</span><span class="p">)</span>
<span class="w">    </span><span class="p">});</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="rest-api-documentation">
<h3><a class="toc-backref" href="#id104" role="doc-backlink">REST API documentation</a><a class="headerlink" href="#rest-api-documentation" title="Permalink to this heading"></a></h3>
<p>Ceph-Dashboard provides two types of documentation for the <strong>Ceph RESTful API</strong>:</p>
<ul class="simple">
<li><p><strong>Static documentation</strong>: available at <a class="reference internal" href="../../../mgr/ceph_api/#mgr-ceph-api"><span class="std std-ref">Ceph RESTful API</span></a>. This comes from a versioned specification located at <code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/openapi.yaml</span></code>.</p></li>
<li><p><strong>Interactive documentation</strong>: available from a running Ceph-Dashboard instance (top-right <code class="docutils literal notranslate"><span class="pre">?</span></code> icon &gt; API Docs).</p></li>
</ul>
<p>If changes are made to the <code class="docutils literal notranslate"><span class="pre">controllers/</span></code> directory, it’s very likely that
they will result in changes to the generated OpenAPI specification. For that
reason, a checker has been implemented to block unintended changes. This check
is automatically triggered by the Pull Request CI (<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check</span></code>) and can be
also manually invoked: <code class="docutils literal notranslate"><span class="pre">tox</span> <span class="pre">-e</span> <span class="pre">openapi-check</span></code>.</p>
<p>If that checker failed, it means that the current Pull Request is modifying the
Ceph API and therefore:</p>
<ol class="arabic simple">
<li><p>The versioned OpenAPI specification should be updated explicitly: <code class="docutils literal notranslate"><span class="pre">tox</span> <span class="pre">-e</span>
<span class="pre">openapi-fix</span></code>.</p></li>
<li><p>The team &#64;ceph/api will be requested for reviews (this is automated via
GitHub CODEOWNERS), in order to assess the impact of changes.</p></li>
</ol>
<p>Additionally, Sphinx documentation can be generated from the OpenAPI
specification with <code class="docutils literal notranslate"><span class="pre">tox</span> <span class="pre">-e</span> <span class="pre">openapi-doc</span></code>.</p>
<p>The Ceph RESTful OpenAPI specification is dynamically generated from the
<code class="docutils literal notranslate"><span class="pre">Controllers</span></code> in <code class="docutils literal notranslate"><span class="pre">controllers/</span></code> directory.  However, by default it is not
very detailed, so there are two decorators that can and should be used to add
more information:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">&#64;EndpointDoc()</span></code> for documentation of endpoints. It has four optional arguments
(explained below): <code class="docutils literal notranslate"><span class="pre">description</span></code>, <code class="docutils literal notranslate"><span class="pre">group</span></code>, <code class="docutils literal notranslate"><span class="pre">parameters</span></code> and
<code class="docutils literal notranslate"><span class="pre">responses</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&#64;ControllerDoc()</span></code> for documentation of controller or group associated with
the endpoints. It only takes the two first arguments: <code class="docutils literal notranslate"><span class="pre">description</span></code> and
<code class="docutils literal notranslate"><span class="pre">group</span></code>.</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">description</span></code>: A a string with a short (1-2 sentences) description of the object.</p>
<p><code class="docutils literal notranslate"><span class="pre">group</span></code>: By default, an endpoint is grouped together with other endpoints
within the same controller class. <code class="docutils literal notranslate"><span class="pre">group</span></code> is a string that can be used to
assign an endpoint or all endpoints in a class to another controller or a
conceived group name.</p>
<p><code class="docutils literal notranslate"><span class="pre">parameters</span></code>: A dict used to describe path, query or request body parameters.
By default, all parameters for an endpoint are listed on the Swagger UI page,
including information of whether the parameter is optional/required and default
values. However, there will be no description of the parameter and the parameter
type will only be displayed in some cases.
When adding information, each parameters should be described as in the example
below. Note that the parameter type should be expressed as a built-in python
type and not as a string. Allowed values are <code class="docutils literal notranslate"><span class="pre">str</span></code>, <code class="docutils literal notranslate"><span class="pre">int</span></code>, <code class="docutils literal notranslate"><span class="pre">bool</span></code>, <code class="docutils literal notranslate"><span class="pre">float</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@EndpointDoc</span><span class="p">(</span><span class="n">parameters</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;my_string&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of my_string&#39;</span><span class="p">)})</span>
<span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="n">my_string</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p>For body parameters, more complex cases are possible. If the parameter is a
dictionary, the type should be replaced with a <code class="docutils literal notranslate"><span class="pre">dict</span></code> containing its nested
parameters. When describing nested parameters, the same format as other
parameters is used. However, all nested parameters are set as required by default.
If the nested parameter is optional this must be specified as for <code class="docutils literal notranslate"><span class="pre">item2</span></code> in
the example below. If a nested parameters is set to optional, it is also
possible to specify the default value (this will not be provided automatically
for nested parameters).</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@EndpointDoc</span><span class="p">(</span><span class="n">parameters</span><span class="o">=</span><span class="p">{</span>
  <span class="s1">&#39;my_dictionary&#39;</span><span class="p">:</span> <span class="p">({</span>
    <span class="s1">&#39;item1&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of item1&#39;</span><span class="p">),</span>
    <span class="s1">&#39;item2&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of item2&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">),</span>  <span class="c1"># item2 is optional</span>
    <span class="s1">&#39;item3&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of item3&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="s1">&#39;foo&#39;</span><span class="p">),</span>  <span class="c1"># item3 is optional with &#39;foo&#39; as default value</span>
<span class="p">},</span> <span class="s1">&#39;Description of my_dictionary&#39;</span><span class="p">)})</span>
<span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="n">my_dictionary</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p>If the parameter is a <code class="docutils literal notranslate"><span class="pre">list</span></code> of primitive types, the type should be
surrounded with square brackets.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@EndpointDoc</span><span class="p">(</span><span class="n">parameters</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;my_list&#39;</span><span class="p">:</span> <span class="p">([</span><span class="nb">int</span><span class="p">],</span> <span class="s1">&#39;Description of my_list&#39;</span><span class="p">)})</span>
<span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="n">my_list</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p>If the parameter is a <code class="docutils literal notranslate"><span class="pre">list</span></code> with nested parameters, the nested parameters
should be placed in a dictionary and surrounded with square brackets.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@EndpointDoc</span><span class="p">(</span><span class="n">parameters</span><span class="o">=</span><span class="p">{</span>
  <span class="s1">&#39;my_list&#39;</span><span class="p">:</span> <span class="p">([{</span>
    <span class="s1">&#39;list_item&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of list_item&#39;</span><span class="p">),</span>
    <span class="s1">&#39;list_item2&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of list_item2&#39;</span><span class="p">)</span>
<span class="p">}],</span> <span class="s1">&#39;Description of my_list&#39;</span><span class="p">)})</span>
<span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="n">my_list</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">responses</span></code>: A dict used for describing responses. Rules for describing
responses are the same as for request body parameters, with one difference:
responses also needs to be assigned to the related response code as in the
example below:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@EndpointDoc</span><span class="p">(</span><span class="n">responses</span><span class="o">=</span><span class="p">{</span>
  <span class="s1">&#39;400&#39;</span><span class="p">:{</span><span class="s1">&#39;my_response&#39;</span><span class="p">:</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;Description of my_response&#39;</span><span class="p">)}})</span>
<span class="k">def</span> <span class="nf">method</span><span class="p">():</span> <span class="k">pass</span>
</pre></div>
</div>
</section>
<section id="error-handling-in-python">
<h3><a class="toc-backref" href="#id105" role="doc-backlink">Error Handling in Python</a><a class="headerlink" href="#error-handling-in-python" title="Permalink to this heading"></a></h3>
<p>Good error handling is a key requirement in creating a good user experience
and providing a good API.</p>
<p>Dashboard code should not duplicate C++ code. Thus, if error handling in C++
is sufficient to provide good feedback, a new wrapper to catch these errors
is not necessary. On the other hand, input validation is the best place to
catch errors and generate the best error messages. If required, generate
errors as soon as possible.</p>
<p>The backend provides few standard ways of returning errors.</p>
<p>First, there is a generic Internal Server Error:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Status</span> <span class="n">Code</span><span class="p">:</span> <span class="mi">500</span>
<span class="p">{</span>
    <span class="s2">&quot;version&quot;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">cherrypy</span> <span class="n">version</span><span class="p">,</span> <span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span> <span class="mf">13.1.0</span><span class="o">&gt;</span><span class="p">,</span>
    <span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="s2">&quot;The server encountered an unexpected condition which prevented it from fulfilling the request.&quot;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For errors generated by the backend, we provide a standard error
format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Status</span> <span class="n">Code</span><span class="p">:</span> <span class="mi">400</span>
<span class="p">{</span>
    <span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>     <span class="c1"># E.g. &quot;[errno -42] &lt;some error message&gt;&quot;</span>
    <span class="s2">&quot;component&quot;</span><span class="p">:</span> <span class="s2">&quot;rbd&quot;</span><span class="p">,</span>   <span class="c1"># this can be null to represent a global error code</span>
    <span class="s2">&quot;code&quot;</span><span class="p">:</span> <span class="s2">&quot;3&quot;</span><span class="p">,</span>          <span class="c1"># Or a error name, e.g. &quot;code&quot;: &quot;some_error_key&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In case, the API Endpoints uses &#64;ViewCache to temporarily cache results,
the error looks like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Status</span> <span class="n">Code</span> <span class="mi">400</span>
<span class="p">{</span>
    <span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>     <span class="c1"># E.g. &quot;[errno -42] &lt;some error message&gt;&quot;</span>
    <span class="s2">&quot;component&quot;</span><span class="p">:</span> <span class="s2">&quot;rbd&quot;</span><span class="p">,</span>   <span class="c1"># this can be null to represent a global error code</span>
    <span class="s2">&quot;code&quot;</span><span class="p">:</span> <span class="s2">&quot;3&quot;</span><span class="p">,</span>          <span class="c1"># Or a error name, e.g. &quot;code&quot;: &quot;some_error_key&quot;</span>
    <span class="s1">&#39;status&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span>          <span class="c1"># Indicating the @ViewCache error status</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In case, the API Endpoints uses a task the error looks like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Status</span> <span class="n">Code</span> <span class="mi">400</span>
<span class="p">{</span>
    <span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span>     <span class="c1"># E.g. &quot;[errno -42] &lt;some error message&gt;&quot;</span>
    <span class="s2">&quot;component&quot;</span><span class="p">:</span> <span class="s2">&quot;rbd&quot;</span><span class="p">,</span>   <span class="c1"># this can be null to represent a global error code</span>
    <span class="s2">&quot;code&quot;</span><span class="p">:</span> <span class="s2">&quot;3&quot;</span><span class="p">,</span>          <span class="c1"># Or a error name, e.g. &quot;code&quot;: &quot;some_error_key&quot;</span>
    <span class="s2">&quot;task&quot;</span><span class="p">:</span> <span class="p">{</span>             <span class="c1"># Information about the task itself</span>
        <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;taskname&quot;</span><span class="p">,</span>
        <span class="s2">&quot;metadata&quot;</span><span class="p">:</span> <span class="p">{</span><span class="o">...</span><span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Our WebUI should show errors generated by the API to the user. Especially
field-related errors in wizards and dialogs or show non-intrusive notifications.</p>
<p>Handling exceptions in Python should be an exception. In general, we
should have few exception handlers in our project. Per default, propagate
errors to the API, as it will take care of all exceptions anyway. In general,
log the exception by adding <code class="docutils literal notranslate"><span class="pre">logger.exception()</span></code> with a description to the
handler.</p>
<p>We need to distinguish between user errors from internal errors and
programming errors. Using different exception types will ease the
task for the API layer and for the user interface:</p>
<p>Standard Python errors, like <code class="docutils literal notranslate"><span class="pre">SystemError</span></code>, <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> or <code class="docutils literal notranslate"><span class="pre">KeyError</span></code>
will end up as internal server errors in the API.</p>
<p>In general, do not <code class="docutils literal notranslate"><span class="pre">return</span></code> error responses in the REST API. They will be
returned by the  error handler. Instead, raise the appropriate exception.</p>
</section>
<section id="plug-ins">
<h3><a class="toc-backref" href="#id106" role="doc-backlink">Plug-ins</a><a class="headerlink" href="#plug-ins" title="Permalink to this heading"></a></h3>
<p>New functionality can be provided by means of a plug-in architecture. Among the
benefits this approach brings in, loosely coupled development is one of the most
notable. As the Ceph Dashboard grows in feature richness, its code-base becomes
more and more complex. The hook-based nature of a plug-in architecture allows to
extend functionality in a controlled manner, and isolate the scope of the
changes.</p>
<p>Ceph Dashboard relies on <a class="reference external" href="https://pluggy.readthedocs.io">Pluggy</a> to provide
for plug-ing support. On top of pluggy, an interface-based approach has been
implemented, with some safety checks (method override and abstract method
checks).</p>
<p>In order to create a new plugin, the following steps are required:</p>
<ol class="arabic simple">
<li><p>Add a new file under <code class="docutils literal notranslate"><span class="pre">src/pybind/mgr/dashboard/plugins</span></code>.</p></li>
<li><p>Import the <code class="docutils literal notranslate"><span class="pre">PLUGIN_MANAGER</span></code> instance and the <code class="docutils literal notranslate"><span class="pre">Interfaces</span></code>.</p></li>
<li><p>Create a class extending the desired interfaces. The plug-in library will
check if all the methods of the interfaces have been properly overridden.</p></li>
<li><p>Register the plugin in the <code class="docutils literal notranslate"><span class="pre">PLUGIN_MANAGER</span></code> instance.</p></li>
<li><p>Import the plug-in from within the Ceph Dashboard <code class="docutils literal notranslate"><span class="pre">module.py</span></code> (currently no
dynamic loading is implemented).</p></li>
</ol>
<p>The available Mixins (helpers) are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CanMgr</span></code>: provides the plug-in with access to the <code class="docutils literal notranslate"><span class="pre">mgr</span></code> instance under <code class="docutils literal notranslate"><span class="pre">self.mgr</span></code>.</p></li>
</ul>
<p>The available Interfaces are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Initializable</span></code>: requires overriding <code class="docutils literal notranslate"><span class="pre">init()</span></code> hook. This method is run at
the very beginning of the dashboard module, right after all imports have been
performed.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Setupable</span></code>: requires overriding <code class="docutils literal notranslate"><span class="pre">setup()</span></code> hook. This method is run in the
Ceph Dashboard <code class="docutils literal notranslate"><span class="pre">serve()</span></code> method, right after CherryPy has been configured,
but before it is started. It’s a placeholder for the plug-in initialization
logic.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">HasOptions</span></code>: requires overriding <code class="docutils literal notranslate"><span class="pre">get_options()</span></code> hook by returning a list
of <code class="docutils literal notranslate"><span class="pre">Options()</span></code>. The options returned here are added to the
<code class="docutils literal notranslate"><span class="pre">MODULE_OPTIONS</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">HasCommands</span></code>: requires overriding <code class="docutils literal notranslate"><span class="pre">register_commands()</span></code> hook by defining
the commands the plug-in can handle and decorating them with <code class="docutils literal notranslate"><span class="pre">&#64;CLICommand</span></code>.
The commands can be optionally returned, so that they can be invoked
externally (which makes unit testing easier).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">HasControllers</span></code>: requires overriding <code class="docutils literal notranslate"><span class="pre">get_controllers()</span></code> hook by defining
and returning the controllers as usual.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">FilterRequest.BeforeHandler</span></code>: requires overriding
<code class="docutils literal notranslate"><span class="pre">filter_request_before_handler()</span></code> hook. This method receives a
<code class="docutils literal notranslate"><span class="pre">cherrypy.request</span></code> object for processing. A usual implementation of this
method will allow some requests to pass or will raise a <code class="docutils literal notranslate"><span class="pre">cherrypy.HTTPError</span></code>
based on the <code class="docutils literal notranslate"><span class="pre">request</span></code> metadata and other conditions.</p></li>
</ul>
<p>New interfaces and hooks should be added as soon as they are required to
implement new functionality. The above list only comprises the hooks needed for
the existing plugins.</p>
<p>A sample plugin implementation would look like this:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># src/pybind/mgr/dashboard/plugins/mute.py</span>

<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">PLUGIN_MANAGER</span> <span class="k">as</span> <span class="n">PM</span>
<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">interfaces</span> <span class="k">as</span> <span class="n">I</span>

<span class="kn">from</span> <span class="nn">mgr_module</span> <span class="kn">import</span> <span class="n">CLICommand</span><span class="p">,</span> <span class="n">Option</span>
<span class="kn">import</span> <span class="nn">cherrypy</span>

<span class="nd">@PM</span><span class="o">.</span><span class="n">add_plugin</span>
<span class="k">class</span> <span class="nc">Mute</span><span class="p">(</span><span class="n">I</span><span class="o">.</span><span class="n">CanMgr</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">Setupable</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">HasOptions</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">HasCommands</span><span class="p">,</span>
                     <span class="n">I</span><span class="o">.</span><span class="n">FilterRequest</span><span class="o">.</span><span class="n">BeforeHandler</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">HasControllers</span><span class="p">):</span>
  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">get_options</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">[</span><span class="n">Option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s1">&#39;bool&#39;</span><span class="p">)]</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">mute</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">mgr</span><span class="o">.</span><span class="n">get_module_option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">)</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">register_commands</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="nd">@CLICommand</span><span class="p">(</span><span class="s2">&quot;dashboard mute&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">_</span><span class="p">(</span><span class="n">mgr</span><span class="p">):</span>
      <span class="bp">self</span><span class="o">.</span><span class="n">mute</span> <span class="o">=</span> <span class="kc">True</span>
      <span class="bp">self</span><span class="o">.</span><span class="n">mgr</span><span class="o">.</span><span class="n">set_module_option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>
      <span class="k">return</span> <span class="mi">0</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">filter_request_before_handler</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">mute</span><span class="p">:</span>
      <span class="k">raise</span> <span class="n">cherrypy</span><span class="o">.</span><span class="n">HTTPError</span><span class="p">(</span><span class="mi">500</span><span class="p">,</span> <span class="s2">&quot;I&#39;m muted :-x&quot;</span><span class="p">)</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">get_controllers</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="kn">from</span> <span class="nn">..controllers</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

    <span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;/mute&#39;</span><span class="p">)</span>
    <span class="k">class</span> <span class="nc">MuteController</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
      <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="n">_</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">mute</span>

    <span class="k">return</span> <span class="p">[</span><span class="n">MuteController</span><span class="p">]</span>
</pre></div>
</div>
<p>Additionally, a helper for creating plugins <code class="docutils literal notranslate"><span class="pre">SimplePlugin</span></code> is provided. It
facilitates the basic tasks (Options, Commands, and common Mixins). The previous
plugin could be rewritten like this:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">PLUGIN_MANAGER</span> <span class="k">as</span> <span class="n">PM</span>
<span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">interfaces</span> <span class="k">as</span> <span class="n">I</span>
<span class="kn">from</span> <span class="nn">.plugin</span> <span class="kn">import</span> <span class="n">SimplePlugin</span> <span class="k">as</span> <span class="n">SP</span>

<span class="kn">import</span> <span class="nn">cherrypy</span>

<span class="nd">@PM</span><span class="o">.</span><span class="n">add_plugin</span>
<span class="k">class</span> <span class="nc">Mute</span><span class="p">(</span><span class="n">SP</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">Setupable</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">FilterRequest</span><span class="o">.</span><span class="n">BeforeHandler</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span><span class="n">HasControllers</span><span class="p">):</span>
  <span class="n">OPTIONS</span> <span class="o">=</span> <span class="p">[</span>
      <span class="n">SP</span><span class="o">.</span><span class="n">Option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s1">&#39;bool&#39;</span><span class="p">)</span>
  <span class="p">]</span>

  <span class="k">def</span> <span class="nf">shut_up</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">set_option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">mute</span> <span class="o">=</span> <span class="kc">True</span>
    <span class="k">return</span> <span class="mi">0</span>

  <span class="n">COMMANDS</span> <span class="o">=</span> <span class="p">[</span>
      <span class="n">SP</span><span class="o">.</span><span class="n">Command</span><span class="p">(</span><span class="s2">&quot;dashboard mute&quot;</span><span class="p">,</span> <span class="n">handler</span><span class="o">=</span><span class="n">shut_up</span><span class="p">)</span>
  <span class="p">]</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">mute</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_option</span><span class="p">(</span><span class="s1">&#39;mute&#39;</span><span class="p">)</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">filter_request_before_handler</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">mute</span><span class="p">:</span>
      <span class="k">raise</span> <span class="n">cherrypy</span><span class="o">.</span><span class="n">HTTPError</span><span class="p">(</span><span class="mi">500</span><span class="p">,</span> <span class="s2">&quot;I&#39;m muted :-x&quot;</span><span class="p">)</span>

  <span class="nd">@PM</span><span class="o">.</span><span class="n">add_hook</span>
  <span class="k">def</span> <span class="nf">get_controllers</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="kn">from</span> <span class="nn">..controllers</span> <span class="kn">import</span> <span class="n">ApiController</span><span class="p">,</span> <span class="n">RESTController</span>

    <span class="nd">@ApiController</span><span class="p">(</span><span class="s1">&#39;/mute&#39;</span><span class="p">)</span>
    <span class="k">class</span> <span class="nc">MuteController</span><span class="p">(</span><span class="n">RESTController</span><span class="p">):</span>
      <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="n">_</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">mute</span>

    <span class="k">return</span> <span class="p">[</span><span class="n">MuteController</span><span class="p">]</span>
</pre></div>
</div>
</section>
</section>
</section>



<div id="support-the-ceph-foundation" class="admonition note">
  <p class="first admonition-title">Brought to you by the Ceph Foundation</p>
  <p class="last">The Ceph Documentation is a community resource funded and hosted by the non-profit <a href="https://ceph.io/en/foundation/">Ceph Foundation</a>. If you would like to support this and our other efforts, please consider <a href="https://ceph.io/en/foundation/join/">joining now</a>.</p>
</div>


           </div>
           
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="../tests-windows/" class="btn btn-neutral float-left" title="Testing - Windows" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../../dashboard/ui_goals/" class="btn btn-neutral float-right" title="Ceph Dashboard Design Goals" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).</p>
  </div>

   

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>